structured-outputs 0.1.0-beta.2 → 0.1.0-beta.21

package/src/deps/jsr.io/@std/collections/1.0.9/sort_by.ts

@@ -0,0 +1,219 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/** Order option for {@linkcode SortByOptions}. */
+export type Order = "asc" | "desc";
+
+/** Options for {@linkcode sortBy}. */
+export type SortByOptions = {
+  /**
+   * The order to sort the elements in.
+   *
+   * @default {"asc"}
+   */
+  order: Order;
+};
+
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified through the `order`
+ * option. By default, the elements are sorted in ascending order.
+ *
+ * Note: If you want to process any iterable, use the new version of
+ * `sortBy` from `@std/collections/unstable-sort-by`.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to sort.
+ * @param selector The selector function to get the value to sort by.
+ * @param options The options for sorting.
+ *
+ * @returns A new array containing all elements sorted by the selector.
+ *
+ * @example Usage
+ * ```ts
+ * import { sortBy } from "@std/collections/sort-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34 },
+ *   { name: "Kim", age: 42 },
+ *   { name: "John", age: 23 },
+ * ];
+ * const sortedByAge = sortBy(people, (person) => person.age);
+ *
+ * assertEquals(sortedByAge, [
+ *   { name: "John", age: 23 },
+ *   { name: "Anna", age: 34 },
+ *   { name: "Kim", age: 42 },
+ * ]);
+ *
+ * const sortedByAgeDesc = sortBy(people, (person) => person.age, { order: "desc" });
+ *
+ * assertEquals(sortedByAgeDesc, [
+ *   { name: "Kim", age: 42 },
+ *   { name: "Anna", age: 34 },
+ *   { name: "John", age: 23 },
+ * ]);
+ * ```
+ */
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => number,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified through the `order`
+ * option. By default, the elements are sorted in ascending order.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to sort.
+ * @param selector The selector function to get the value to sort by.
+ * @param options The options for sorting.
+ *
+ * @returns A new array containing all elements sorted by the selector.
+ *
+ * @example Usage
+ * ```ts
+ * import { sortBy } from "@std/collections/sort-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const people = [
+ *   { name: "Anna" },
+ *   { name: "Kim" },
+ *   { name: "John" },
+ * ];
+ * const sortedByName = sortBy(people, (it) => it.name);
+ *
+ * assertEquals(sortedByName, [
+ *   { name: "Anna" },
+ *   { name: "John" },
+ *   { name: "Kim" },
+ * ]);
+ * ```
+ */
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => string,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified through the `order`
+ * option. By default, the elements are sorted in ascending order.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to sort.
+ * @param selector The selector function to get the value to sort by.
+ * @param options The options for sorting.
+ *
+ * @returns A new array containing all elements sorted by the selector.
+ *
+ * @example Usage
+ * ```ts
+ * import { sortBy } from "@std/collections/sort-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34n },
+ *   { name: "Kim", age: 42n },
+ *   { name: "John", age: 23n },
+ * ];
+ *
+ * const sortedByAge = sortBy(people, (person) => person.age);
+ *
+ * assertEquals(sortedByAge, [
+ *   { name: "John", age: 23n },
+ *   { name: "Anna", age: 34n },
+ *   { name: "Kim", age: 42n },
+ * ]);
+ * ```
+ */
+
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => bigint,
+  options?: SortByOptions,
+): T[];
+/**
+ * Returns all elements in the given collection, sorted by their result using
+ * the given selector. The selector function is called only once for each
+ * element. Ascending or descending order can be specified through the `order`
+ * option. By default, the elements are sorted in ascending order.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to sort.
+ * @param selector The selector function to get the value to sort by.
+ * @param options The options for sorting.
+ *
+ * @returns A new array containing all elements sorted by the selector.
+ *
+ * @example Usage
+ * ```ts
+ * import { sortBy } from "@std/collections/sort-by";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const people = [
+ *   { name: "Anna", startedAt: new Date("2020-01-01") },
+ *   { name: "Kim", startedAt: new Date("2020-03-01") },
+ *   { name: "John", startedAt: new Date("2020-06-01") },
+ * ];
+ *
+ * const sortedByStartedAt = sortBy(people, (people) => people.startedAt);
+ *
+ * assertEquals(sortedByStartedAt, [
+ *   { name: "Anna", startedAt: new Date("2020-01-01") },
+ *   { name: "Kim", startedAt: new Date("2020-03-01") },
+ *   { name: "John", startedAt: new Date("2020-06-01") },
+ * ]);
+ * ```
+ */
+export function sortBy<T>(
+  array: readonly T[],
+  selector: (el: T) => Date,
+  options?: SortByOptions,
+): T[];
+export function sortBy<T>(
+  array: readonly T[],
+  selector:
+    | ((el: T) => number)
+    | ((el: T) => string)
+    | ((el: T) => bigint)
+    | ((el: T) => Date),
+  options?: SortByOptions,
+): T[] {
+  const len = array.length;
+  const indexes = new Array<number>(len);
+  const selectors = new Array<ReturnType<typeof selector> | null>(len);
+  const order = options?.order ?? "asc";
+
+  array.forEach((element, index) => {
+    indexes[index] = index;
+    const selected = selector(element);
+    selectors[index] = Number.isNaN(selected) ? null : selected;
+  });
+
+  indexes.sort((ai, bi) => {
+    let a = selectors[ai]!;
+    let b = selectors[bi]!;
+    if (order === "desc") {
+      [a, b] = [b, a];
+    }
+    if (a === null) return 1;
+    if (b === null) return -1;
+    return a > b ? 1 : a < b ? -1 : 0;
+  });
+
+  for (let i = 0; i < len; i++) {
+    (indexes as unknown as T[])[i] = array[indexes[i]!] as T;
+  }
+
+  return indexes as unknown as T[];
+}

package/src/deps/jsr.io/@std/collections/1.0.9/sum_of.ts

@@ -0,0 +1,42 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Applies the given selector to all elements in the given collection and
+ * calculates the sum of the results.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to calculate the sum of.
+ * @param selector The selector function to get the value to sum.
+ *
+ * @returns The sum of all elements in the collection.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { sumOf } from "@std/collections/sum-of";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const people = [
+ *   { name: "Anna", age: 34 },
+ *   { name: "Kim", age: 42 },
+ *   { name: "John", age: 23 },
+ * ];
+ *
+ * const totalAge = sumOf(people, (person) => person.age);
+ *
+ * assertEquals(totalAge, 99);
+ * ```
+ */
+export function sumOf<T>(
+  array: Iterable<T>,
+  selector: (el: T) => number,
+): number {
+  let sum = 0;
+
+  for (const i of array) {
+    sum += selector(i);
+  }
+
+  return sum;
+}

package/src/deps/jsr.io/@std/collections/1.0.9/take_last_while.ts

@@ -0,0 +1,37 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Returns all elements in the given array after the last element that does not
+ * match the given predicate.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to take elements from.
+ * @param predicate The predicate function to determine if an element should be
+ * included.
+ *
+ * @returns A new array containing all elements after the last element that does
+ * not match the predicate.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { takeLastWhile } from "@std/collections/take-last-while";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const numbers = [1, 2, 3, 4, 5, 6];
+ *
+ * const result = takeLastWhile(numbers, (number) => number > 4);
+ *
+ * assertEquals(result, [5, 6]);
+ * ```
+ */
+export function takeLastWhile<T>(
+  array: readonly T[],
+  predicate: (el: T) => boolean,
+): T[] {
+  let offset = array.length;
+  while (0 < offset && predicate(array[offset - 1] as T)) offset--;
+
+  return array.slice(offset, array.length);
+}

package/src/deps/jsr.io/@std/collections/1.0.9/take_while.ts

@@ -0,0 +1,44 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Returns all elements in the given collection until the first element that
+ * does not match the given predicate.
+ *
+ * Note: If you want to process any iterable, use the new version of
+ * `takeWhile` from `@std/collections/unstable-take-while`.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to take elements from.
+ * @param predicate The predicate function to determine if an element should be
+ * included.
+ *
+ * @returns A new array containing all elements until the first element that
+ * does not match the predicate.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { takeWhile } from "@std/collections/take-while";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const numbers = [1, 2, 3, 4, 5, 6];
+ *
+ * const result = takeWhile(numbers, (number) => number < 4);
+ *
+ * assertEquals(result, [1, 2, 3]);
+ * ```
+ */
+export function takeWhile<T>(
+  array: readonly T[],
+  predicate: (el: T) => boolean,
+): T[] {
+  let offset = 0;
+  const length = array.length;
+
+  while (length > offset && predicate(array[offset] as T)) {
+    offset++;
+  }
+
+  return array.slice(0, offset);
+}

package/src/deps/jsr.io/@std/collections/1.0.9/union.ts

@@ -0,0 +1,36 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Returns all distinct elements that appear in any of the given arrays.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param arrays The arrays to get the union of.
+ *
+ * @returns A new array containing all distinct elements from the given arrays.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { union } from "@std/collections/union";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const soupIngredients = ["Pepper", "Carrots", "Leek"];
+ * const saladIngredients = ["Carrots", "Radicchio", "Pepper"];
+ *
+ * const shoppingList = union(soupIngredients, saladIngredients);
+ *
+ * assertEquals(shoppingList, ["Pepper", "Carrots", "Leek", "Radicchio"]);
+ * ```
+ */
+export function union<T>(...arrays: Iterable<T>[]): T[] {
+  const set = new Set<T>();
+
+  for (const array of arrays) {
+    for (const element of array) {
+      set.add(element);
+    }
+  }
+
+  return Array.from(set);
+}

package/src/deps/jsr.io/@std/collections/1.0.9/unzip.ts

@@ -0,0 +1,50 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Builds two separate arrays from the given array of 2-tuples, with the first
+ * returned array holding all first tuple elements and the second one holding
+ * all the second elements.
+ *
+ * @typeParam T The type of the first tuple elements.
+ * @typeParam U The type of the second tuple elements.
+ *
+ * @param pairs The array of 2-tuples to unzip.
+ *
+ * @returns A tuple containing two arrays, the first one holding all first tuple
+ * elements and the second one holding all second elements.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { unzip } from "@std/collections/unzip";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const parents = [
+ *   ["Maria", "Jeff"],
+ *   ["Anna", "Kim"],
+ *   ["John", "Leroy"],
+ * ] as [string, string][];
+ *
+ * const [moms, dads] = unzip(parents);
+ *
+ * assertEquals(moms, ["Maria", "Anna", "John"]);
+ * assertEquals(dads, ["Jeff", "Kim", "Leroy"]);
+ * ```
+ */
+export function unzip<T, U>(pairs: readonly [T, U][]): [T[], U[]] {
+  const { length } = pairs;
+
+  const result: [T[], U[]] = [
+    new Array<T>(length),
+    new Array<U>(length),
+  ];
+
+  for (let i = 0; i < length; ++i) {
+    const pair = pairs[i] as [T, U];
+
+    result[0][i] = pair[0];
+    result[1][i] = pair[1];
+  }
+
+  return result;
+}

package/src/deps/jsr.io/@std/collections/1.0.9/without_all.ts

@@ -0,0 +1,28 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * Returns an array excluding all given values.
+ *
+ * @typeParam T The type of the array elements.
+ *
+ * @param array The array to exclude values from.
+ * @param values The values to exclude from the array.
+ *
+ * @returns A new array containing all elements from the given array except the
+ * ones that are in the values array.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { withoutAll } from "@std/collections/without-all";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const withoutList = withoutAll([2, 1, 2, 3], [1, 2]);
+ *
+ * assertEquals(withoutList, [3]);
+ * ```
+ */
+export function withoutAll<T>(array: readonly T[], values: readonly T[]): T[] {
+  const toExclude = new Set(values);
+  return array.filter((it) => !toExclude.has(it));
+}

package/src/deps/jsr.io/@std/collections/1.0.9/zip.ts

@@ -0,0 +1,49 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { minOf } from "./min_of.js";
+
+/**
+ * Builds N-tuples of elements from the given N arrays with matching indices,
+ * stopping when the smallest array's end is reached.
+ *
+ * @typeParam T the type of the tuples produced by this function.
+ *
+ * @param arrays The arrays to zip.
+ *
+ * @returns A new array containing N-tuples of elements from the given arrays.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { zip } from "@std/collections/zip";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const numbers = [1, 2, 3, 4];
+ * const letters = ["a", "b", "c", "d"];
+ * const pairs = zip(numbers, letters);
+ *
+ * assertEquals(
+ *   pairs,
+ *   [
+ *     [1, "a"],
+ *     [2, "b"],
+ *     [3, "c"],
+ *     [4, "d"],
+ *   ],
+ * );
+ * ```
+ */
+export function zip<T extends unknown[]>(
+  ...arrays: { [K in keyof T]: ReadonlyArray<T[K]> }
+): T[] {
+  const minLength = minOf(arrays, (element) => element.length) ?? 0;
+
+  const result: T[] = new Array(minLength);
+
+  for (let i = 0; i < minLength; i += 1) {
+    const arr = arrays.map((it) => it[i]);
+    result[i] = arr as T;
+  }
+
+  return result;
+}

package/src/mod.ts

@@ -1,19 +1,4 @@
-import type { ArrayTy } from "./array.js"
-import type { NumberTy } from "./number.js"
-import type { ObjectTy } from "./object.js"
-import type { StringTy } from "./string.js"
-
-export type RootTy = NumberTy | StringTy | ObjectTy | ArrayTy
-
-// moderate --exclude _base.ts code_critique.ts
-
-export * from "./array.js"
-export * from "./common.js"
-export * from "./F.js"
-export * from "./literal.js"
-export * from "./number.js"
-export * from "./object.js"
+import "./_dnt.polyfills.js";
+export * as T from "./types/mod.js"
 export * from "./ResponseFormat.js"
-export * from "./schema.js"
-export * from "./string.js"
-export * from "./union.js"
+export * from "./Tool.js"

package/src/oai.ts

@@ -0,0 +1,5 @@
+import type Openai from "openai"
+
+export type JsonSchema = Openai.ResponseFormatJSONSchema["json_schema"]
+export type ChatCompletion = Openai.Chat.ChatCompletion
+export type ChatCompletionChoice = Openai.Chat.Completions.ChatCompletion.Choice

package/src/types/Ref.ts

@@ -0,0 +1,16 @@
+import type { Applied, Schema, Ty } from "./Ty.js"
+import { recombineTaggedTemplateArgs } from "../util/recombineTaggedTemplateArgs.js"
+
+export type Ref = (ty: Ty) => Schema
+
+export function Ref(applied: Applied): Ref {
+  return (ty) => {
+    applied = { ...applied, ...ty.applied }
+    const description = ty.descriptions
+      .map(({ template, placeheld }) =>
+        recombineTaggedTemplateArgs(template, placeheld.map((k) => applied[k]!))
+      )
+      .join(" ")
+    return ty.toSchema(description, Ref(applied))
+  }
+}

package/src/types/RootTy.ts

@@ -0,0 +1,40 @@
+import { phantoms } from "../util/phantoms.js"
+import { Ref } from "./Ref.js"
+import type { Applied, Description, Schema, ToSchema, Ty } from "./Ty.js"
+
+export function RootTy<T, P extends string = never>(
+  toSchema: ToSchema,
+  descriptions: Array<Description> = [],
+  applied: Applied = {},
+): RootTy<T, P> {
+  return Object.assign(
+    <P2 extends Array<string>>(template: TemplateStringsArray, ...placeheld: P2) =>
+      RootTy<T, P | P2[number]>(toSchema, [{ template, placeheld }, ...descriptions], applied),
+    phantoms<{ [Ty.T]: T; [Ty.P]: P }>(),
+    {
+      toSchema,
+      descriptions,
+      applied,
+      apply: <A extends Partial<Record<P, string | number>>>(values: A) => {
+        return RootTy<T, Exclude<P, keyof A>>(toSchema, descriptions, { ...applied, ...values })
+      },
+      schema(this: RootTy<T, never>) {
+        return Ref({})(this)
+      },
+      isRoot(): this is RootTy {
+        return true
+      },
+    },
+  )
+}
+
+export interface RootTy<T = any, P extends string = string> extends Ty<T, P> {
+  <P2 extends Array<string>>(
+    template: TemplateStringsArray,
+    ...placeheld: P2
+  ): RootTy<T, P | P2[number]>
+  apply: <A extends Partial<Record<P, number | string>>>(
+    values: A,
+  ) => RootTy<T, Exclude<P, keyof A>>
+  schema(this: RootTy<T, never>): Schema
+}

package/src/types/Ty.ts

@@ -0,0 +1,57 @@
+import type { Ref } from "./Ref.js"
+import { phantoms } from "../util/phantoms.js"
+import type { RootTy } from "./RootTy.js"
+
+export function Ty<T, P extends string = never>(
+  toSchema: ToSchema,
+  descriptions: Array<Description> = [],
+  applied: Applied = {},
+): Ty<T, P> {
+  return Object.assign(
+    <P2 extends Array<string>>(template: TemplateStringsArray, ...placeheld: P2) =>
+      Ty<T, P | P2[number]>(toSchema, [{ template, placeheld }, ...descriptions], applied),
+    phantoms<{ [Ty.T]: T; [Ty.P]: P }>(),
+    {
+      toSchema,
+      descriptions,
+      applied,
+      apply: <A extends Partial<Record<P, string | number>>>(values: A) => {
+        return Ty<T, Exclude<P, keyof A>>(toSchema, descriptions, { ...applied, ...values })
+      },
+      isRoot(): this is RootTy {
+        return false
+      },
+    },
+  )
+}
+
+export interface Ty<T = any, P extends string = string> {
+  <P2 extends Array<string>>(
+    template: TemplateStringsArray,
+    ...placeheld: P2
+  ): Ty<T, P | P2[number]>
+  [Ty.T]: T
+  [Ty.P]: P
+  toSchema: ToSchema
+  descriptions: Array<Description>
+  applied: Applied
+  apply: <A extends Partial<Record<P, number | string>>>(values: A) => Ty<T, Exclude<P, keyof A>>
+  isRoot(): this is RootTy
+}
+
+export namespace Ty {
+  export type T = typeof T
+  export declare const T: unique symbol
+  export type P = typeof P
+  export declare const P: unique symbol
+}
+
+export type ToSchema = (description: string | undefined, ref: Ref) => Schema
+export type Schema = Record<string, unknown>
+
+export interface Description {
+  template: TemplateStringsArray
+  placeheld: Array<string>
+}
+
+export type Applied = Record<string, number | string>

package/src/types/array.ts

@@ -0,0 +1,9 @@
+import { Ty } from "./Ty.js"
+
+export function array<E extends Ty>(element: E): Ty<Array<E[Ty.T]>, E[Ty.P]> {
+  return Ty((description, ref) => ({
+    type: "array",
+    description,
+    items: ref(element),
+  }))
+}

package/src/types/constant.ts

@@ -0,0 +1,8 @@
+import { Ty } from "./Ty.js"
+
+export function constant<V extends number | string>(value: V): Ty<V, never> {
+  return Ty((description) => ({
+    const: value,
+    description,
+  }))
+}