feat: Introduce uniqueOneOf function for reusable unique selection in schema generation. Update README and documentation to reflect new option structure, including support for weighted items and improved error handling for exhausted collections.

Author: Michal Warda

README.md

@@ -223,26 +223,43 @@ const schema = () => [
 
 #### Unique draws across a dataset
 
-Pass a `uniqueBy` configuration when you need each option to be used at most once across every row/schema during generation:
+Pass a `uniqueBy` configuration when you need each option to be used at most once across every row/schema during generation. When using `uniqueBy`, each option must be an object with `id`, `value`, and optionally `weight`:
 
 ```ts
 const toolOptions = [
-  weatherTool.toolFunction(),
-  calendarTool.toolFunction(),
-  flightTool.toolFunction(),
-] as const;
+  { id: "weather", value: weatherTool.toolFunction() },
+  { id: "calendar", value: calendarTool.toolFunction() },
+  { id: "flight", value: flightTool.toolFunction() },
+];
+
+const schema = () => [
+  oneOf(toolOptions, {
+    uniqueBy: {
+      collection: "tools",
+    },
+  }),
+];
+```
+
+You can also combine `uniqueBy` with weighted options:
+
+```ts
+const toolOptions = [
+  { id: "weather", value: weatherTool.toolFunction(), weight: 0.5 },
+  { id: "calendar", value: calendarTool.toolFunction(), weight: 0.3 },
+  { id: "flight", value: flightTool.toolFunction(), weight: 0.2 },
+];
 
 const schema = () => [
   oneOf(toolOptions, {
     uniqueBy: {
       collection: "tools",
-      itemId: "name",
     },
   }),
 ];
 ```
 
-The `collection` name identifies the shared pool (so multiple `oneOf` calls can coordinate), and `itemId` can be either a property key or a function that returns a stable identifier. Omit `itemId` to default to the common `id` field. Torque throws if the pool is exhausted, making it easy to guarantee perfect round-robin coverage.
+The `collection` name identifies the shared pool (so multiple `oneOf` calls can coordinate). The `id` property must be a string, number, or boolean and is used to track uniqueness. Torque throws if the pool is exhausted, making it easy to guarantee perfect round-robin coverage.
 
 > 💡 See weighted example: [`examples/weighted-one-of.ts`](examples/weighted-one-of.ts)  
 > 💡 Full utilities demo: [`examples/composition-utilities.ts`](examples/composition-utilities.ts) | [▶️ Try in Browser](https://stackblitz.com/github/qforge-dev/torque/tree/main/stackblitz-templates/composition-utilities)

packages/torque/README.md

@@ -232,26 +232,43 @@ const schema = () => [
 
 #### Unique draws across a dataset
 
-Pass a `uniqueBy` configuration when you need each option to be used at most once across every row/schema during generation:
+Pass a `uniqueBy` configuration when you need each option to be used at most once across every row/schema during generation. When using `uniqueBy`, each option must be an object with `id`, `value`, and optionally `weight`:
 
 ```ts
 const toolOptions = [
-  weatherTool.toolFunction(),
-  calendarTool.toolFunction(),
-  flightTool.toolFunction(),
-] as const;
+  { id: "weather", value: weatherTool.toolFunction() },
+  { id: "calendar", value: calendarTool.toolFunction() },
+  { id: "flight", value: flightTool.toolFunction() },
+];
+
+const schema = () => [
+  oneOf(toolOptions, {
+    uniqueBy: {
+      collection: "tools",
+    },
+  }),
+];
+```
+
+You can also combine `uniqueBy` with weighted options:
+
+```ts
+const toolOptions = [
+  { id: "weather", value: weatherTool.toolFunction(), weight: 0.5 },
+  { id: "calendar", value: calendarTool.toolFunction(), weight: 0.3 },
+  { id: "flight", value: flightTool.toolFunction(), weight: 0.2 },
+];
 
 const schema = () => [
   oneOf(toolOptions, {
     uniqueBy: {
       collection: "tools",
-      itemId: "name",
     },
   }),
 ];
 ```
 
-The `collection` name identifies the shared pool (so multiple `oneOf` calls can coordinate), and `itemId` can be either a property key or a function that returns a stable identifier. Omit `itemId` to default to the common `id` field. Torque throws if the pool is exhausted, making it easy to guarantee perfect round-robin coverage.
+The `collection` name identifies the shared pool (so multiple `oneOf` calls can coordinate). The `id` property must be a string, number, or boolean and is used to track uniqueness. Torque throws if the pool is exhausted, making it easy to guarantee perfect round-robin coverage.
 
 > 💡 See weighted example: [`examples/weighted-one-of.ts`](examples/weighted-one-of.ts)  
 > 💡 Full utilities demo: [`examples/composition-utilities.ts`](examples/composition-utilities.ts) | [▶️ Try in Browser](https://stackblitz.com/github/qforge-dev/torque/tree/main/stackblitz-templates/composition-utilities)

packages/torque/src/schema-rng.ts

@@ -59,6 +59,76 @@ export function randomSample<T>(n: number, array: T[]): T[] {
   return result;
 }
 
+function generateRandomId(): string {
+  const randA = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+  const randB = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+  return `${randA.toString(36)}${randB.toString(36)}`;
+}
+
+function generateRandomCollectionName(): string {
+  const randA = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+  const randB = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+  return `col_${randA.toString(36)}${randB.toString(36)}`;
+}
+
+/**
+ * Factory function that creates a reusable oneOf function with unique selection.
+ * Converts an array of items (or weighted items) into a collection of objects with random IDs,
+ * and returns a function that can be called during schema generation to select
+ * unique items from the collection.
+ *
+ * @param items - Array of items or weighted items to create unique selection from
+ * @returns A function that when called, returns a unique item from the collection
+ *
+ * @example
+ * ```ts
+ * // Plain items
+ * const tools = [weatherTool, calendarTool, flightTool];
+ * const oneOfTools = uniqueOneOf(tools);
+ *
+ * // Weighted items
+ * const weightedTools = [
+ *   { value: weatherTool, weight: 0.5 },
+ *   { value: calendarTool, weight: 0.3 },
+ *   flightTool, // unweighted, gets remaining weight
+ * ];
+ * const oneOfWeightedTools = uniqueOneOf(weightedTools);
+ *
+ * const schema = () => [
+ *   oneOfTools(), // Returns a unique tool each time
+ * ];
+ * ```
+ */
+export function uniqueOneOf<T>(items: Array<WeightedOneOfOption<T>>): () => T {
+  if (items.length === 0) {
+    throw new Error("uniqueOneOf requires at least one item");
+  }
+
+  const collection = generateRandomCollectionName();
+  const optionsWithIds: OneOfOptionWithId<T>[] = items.map((item) => {
+    if (isWeightedOption(item)) {
+      return {
+        id: generateRandomId(),
+        value: item.value,
+        weight: item.weight,
+      };
+    } else {
+      return {
+        id: generateRandomId(),
+        value: item,
+      };
+    }
+  });
+
+  return () => {
+    return oneOf(optionsWithIds, {
+      uniqueBy: {
+        collection,
+      },
+    });
+  };
+}
+
 export function oneOf<T>(
   options: Array<OneOfOptionWithId<T>>,
   config: { uniqueBy: OneOfUniqueBy }

packages/torque/src/schema.test.ts

@@ -6,7 +6,7 @@ import {
   generatedAssistant,
   assistant,
 } from "./schema";
-import { oneOf } from "./schema-rng";
+import { oneOf, uniqueOneOf } from "./schema-rng";
 import type { IMessageSchemaContext } from "./types";
 import { withSeed } from "./utils";
 import { MockLanguageModelV2 } from "ai/test";
@@ -140,6 +140,60 @@ describe("oneOf", () => {
       });
     });
   });
+
+  it("uniqueOneOf creates a reusable oneOf function with unique selection", async () => {
+    const tools = ["weather", "calendar", "flight"];
+
+    const oneOfTools = uniqueOneOf(tools);
+
+    await runWithUniqueSelectionScope(async () => {
+      const picks = [oneOfTools(), oneOfTools(), oneOfTools()];
+
+      expect(new Set(picks).size).toBe(3);
+      picks.forEach((pick) => {
+        expect(tools).toContain(pick);
+      });
+    });
+  });
+
+  it("uniqueOneOf throws when collection is exhausted", async () => {
+    const tools = ["only"];
+
+    const oneOfTools = uniqueOneOf(tools);
+
+    await runWithUniqueSelectionScope(async () => {
+      oneOfTools(); // First call succeeds
+
+      expect(() => {
+        oneOfTools(); // Second call should throw
+      }).toThrow("oneOf uniqueBy collection");
+    });
+  });
+
+  it("uniqueOneOf works with weighted options", async () => {
+    const weightedTools = [
+      { value: "weather", weight: 0.5 },
+      { value: "calendar", weight: 0.3 },
+      "flight", // unweighted, gets remaining weight
+    ];
+
+    const oneOfTools = uniqueOneOf(weightedTools);
+
+    await runWithUniqueSelectionScope(async () => {
+      await withSeed(100, async () => {
+        const first = oneOfTools();
+        expect(["weather", "calendar", "flight"]).toContain(first);
+
+        const second = oneOfTools();
+        expect(["weather", "calendar", "flight"]).toContain(second);
+        expect(second).not.toBe(first);
+
+        const third = oneOfTools();
+        expect(["weather", "calendar", "flight"]).toContain(third);
+        expect(new Set([first, second, third]).size).toBe(3);
+      });
+    });
+  });
 });
 
 describe("metadata helper", () => {