@fgv/ts-json-base 5.1.0-33 → 5.1.0-35

package/lib/packlets/json-schema-builder/types.d.ts

@@ -0,0 +1,142 @@
+import { Validator } from '@fgv/ts-utils';
+import { JsonObject } from '../json';
+/**
+ * Discriminant tag carried by every schema node.
+ * @public
+ */
+export type SchemaNodeType = 'string' | 'number' | 'integer' | 'boolean' | 'enum' | 'optional' | 'array' | 'object';
+/**
+ * A typed JSON Schema node for the LLM-tool subset. Every value returned by the
+ * schema factories implements this interface — it IS a `Validator<T>` and also
+ * carries a `toJson()` method for wire-format emission.
+ *
+ * @remarks
+ * The `__staticType` property is a phantom: it exists only in the type system to carry
+ * the derived static type `T` and is never assigned at runtime (declared optional so
+ * factory return values need not populate it). `Static<S>` reads this slot to recover
+ * `T` from a schema value without requiring a user-supplied type assertion. A plain
+ * optional property is used rather than a module-private `unique symbol` because this is
+ * a published package surface — a private-symbol-keyed property cannot be named in the
+ * emitted `.d.ts` (TypeBox issue #679), which would break declaration emission and API
+ * Extractor for downstream consumers.
+ *
+ * Consumers call `schema.validate(input)` directly; no separate adapter step is required.
+ * @public
+ */
+export interface ISchemaValidator<T> extends Validator<T> {
+    /**
+     * Phantom type carrier — type-level only, never present at runtime.
+     */
+    readonly __staticType?: T;
+    /**
+     * Runtime discriminant. Identifies the schema node kind.
+     */
+    readonly _type: SchemaNodeType;
+    /**
+     * Optional human-readable description emitted into the wire JSON Schema.
+     */
+    readonly description?: string;
+    /**
+     * Emits the standard JSON Schema (draft-07 LLM-tool subset) wire form for this schema.
+     * @returns The JSON Schema object describing this schema node.
+     */
+    toJson(): JsonObject;
+}
+/**
+ * Recover the derived static type `T` from a schema value.
+ *
+ * @remarks
+ * `Static<typeof MySchema>` resolves to the TypeScript type that `schema.validate()` produces
+ * and that `schema.toJson()` describes — derived, never asserted. No user-supplied `T` is ever
+ * required.
+ * @public
+ */
+export type Static<S extends ISchemaValidator<unknown>> = S extends ISchemaValidator<infer T> ? T : never;
+/**
+ * A record of property schemas, as accepted by the `object` factory.
+ * @public
+ */
+export type ILlmProperties = Record<string, ISchemaValidator<unknown>>;
+/**
+ * The keys of `P` whose schemas are optional (wrapped with the `optional` modifier).
+ * @public
+ */
+export type OptionalKeys<P extends ILlmProperties> = {
+    [K in keyof P]: P[K] extends ISchemaValidator<infer U> ? (undefined extends U ? K : never) : never;
+}[keyof P];
+/**
+ * The keys of `P` whose schemas are required (i.e. not optional).
+ * @public
+ */
+export type RequiredKeys<P extends ILlmProperties> = Exclude<keyof P, OptionalKeys<P>>;
+/**
+ * The static value type carried by an optional property (the inner schema's static type,
+ * without the `| undefined` that optionality adds — the `?` modifier conveys that separately).
+ * @public
+ */
+export type OptionalPropertyStatic<V> = V extends ISchemaValidator<infer U> ? Exclude<U, undefined> : never;
+/**
+ * Flattens an intersection of object types into a single object type for readable derived types.
+ * @public
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The derived static type for an object built from properties `P`: required keys carry their
+ * static type directly, optional keys carry theirs under a `?` modifier.
+ * @public
+ */
+export type ObjectStatic<P extends ILlmProperties> = Simplify<{
+    [K in RequiredKeys<P>]: Static<P[K]>;
+} & {
+    [K in OptionalKeys<P>]?: OptionalPropertyStatic<P[K]>;
+}>;
+/**
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmSchema<T> = ISchemaValidator<T>;
+/**
+ * Schema node for a JSON `string`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmStringSchema = ISchemaValidator<string>;
+/**
+ * Schema node for a JSON `number` or `integer`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmNumberSchema = ISchemaValidator<number>;
+/**
+ * Schema node for a JSON `boolean`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmBooleanSchema = ISchemaValidator<boolean>;
+/**
+ * Schema node for a closed set of string literals (`enum`).
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmEnumSchema<T extends string> = ISchemaValidator<T>;
+/**
+ * Wrapper marking a property as optional within an object schema.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmOptional<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S> | undefined>;
+/**
+ * Schema node for a JSON `array`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmArraySchema<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S>[]>;
+/**
+ * Schema node for a JSON `object`.
+ * @deprecated Use `ISchemaValidator` instead.
+ * @public
+ */
+export type ILlmObjectSchema<P extends ILlmProperties> = ISchemaValidator<ObjectStatic<P>>;
+//# sourceMappingURL=types.d.ts.map

package/lib/packlets/json-schema-builder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/packlets/json-schema-builder/types.ts"],"names":[],"mappings":"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"}

package/lib/packlets/json-schema-builder/types.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/packlets/json-schema-builder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/packlets/json-schema-builder/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Validator } from '@fgv/ts-utils';\nimport { JsonObject } from '../json';\n\n/**\n * Discriminant tag carried by every schema node.\n * @public\n */\nexport type SchemaNodeType =\n  | 'string'\n  | 'number'\n  | 'integer'\n  | 'boolean'\n  | 'enum'\n  | 'optional'\n  | 'array'\n  | 'object';\n\n/**\n * A typed JSON Schema node for the LLM-tool subset. Every value returned by the\n * schema factories implements this interface — it IS a `Validator<T>` and also\n * carries a `toJson()` method for wire-format emission.\n *\n * @remarks\n * The `__staticType` property is a phantom: it exists only in the type system to carry\n * the derived static type `T` and is never assigned at runtime (declared optional so\n * factory return values need not populate it). `Static<S>` reads this slot to recover\n * `T` from a schema value without requiring a user-supplied type assertion. A plain\n * optional property is used rather than a module-private `unique symbol` because this is\n * a published package surface — a private-symbol-keyed property cannot be named in the\n * emitted `.d.ts` (TypeBox issue #679), which would break declaration emission and API\n * Extractor for downstream consumers.\n *\n * Consumers call `schema.validate(input)` directly; no separate adapter step is required.\n * @public\n */\nexport interface ISchemaValidator<T> extends Validator<T> {\n  /**\n   * Phantom type carrier — type-level only, never present at runtime.\n   */\n  readonly __staticType?: T;\n  /**\n   * Runtime discriminant. Identifies the schema node kind.\n   */\n  readonly _type: SchemaNodeType;\n  /**\n   * Optional human-readable description emitted into the wire JSON Schema.\n   */\n  readonly description?: string;\n  /**\n   * Emits the standard JSON Schema (draft-07 LLM-tool subset) wire form for this schema.\n   * @returns The JSON Schema object describing this schema node.\n   */\n  toJson(): JsonObject;\n}\n\n/**\n * Recover the derived static type `T` from a schema value.\n *\n * @remarks\n * `Static<typeof MySchema>` resolves to the TypeScript type that `schema.validate()` produces\n * and that `schema.toJson()` describes — derived, never asserted. No user-supplied `T` is ever\n * required.\n * @public\n */\nexport type Static<S extends ISchemaValidator<unknown>> = S extends ISchemaValidator<infer T> ? T : never;\n\n/**\n * A record of property schemas, as accepted by the `object` factory.\n * @public\n */\nexport type ILlmProperties = Record<string, ISchemaValidator<unknown>>;\n\n/**\n * The keys of `P` whose schemas are optional (wrapped with the `optional` modifier).\n * @public\n */\nexport type OptionalKeys<P extends ILlmProperties> = {\n  [K in keyof P]: P[K] extends ISchemaValidator<infer U> ? (undefined extends U ? K : never) : never;\n}[keyof P];\n\n/**\n * The keys of `P` whose schemas are required (i.e. not optional).\n * @public\n */\nexport type RequiredKeys<P extends ILlmProperties> = Exclude<keyof P, OptionalKeys<P>>;\n\n/**\n * The static value type carried by an optional property (the inner schema's static type,\n * without the `| undefined` that optionality adds — the `?` modifier conveys that separately).\n * @public\n */\nexport type OptionalPropertyStatic<V> = V extends ISchemaValidator<infer U> ? Exclude<U, undefined> : never;\n\n/**\n * Flattens an intersection of object types into a single object type for readable derived types.\n * @public\n */\nexport type Simplify<T> = { [K in keyof T]: T[K] } & {};\n\n/**\n * The derived static type for an object built from properties `P`: required keys carry their\n * static type directly, optional keys carry theirs under a `?` modifier.\n * @public\n */\nexport type ObjectStatic<P extends ILlmProperties> = Simplify<\n  { [K in RequiredKeys<P>]: Static<P[K]> } & { [K in OptionalKeys<P>]?: OptionalPropertyStatic<P[K]> }\n>;\n\n// ---------------------------------------------------------------------------\n// Legacy type aliases kept for backwards compatibility with the first-pass API.\n// These names were in the original public surface; the canonical interface is\n// now ISchemaValidator<T>. New code should use ISchemaValidator<T> directly.\n// ---------------------------------------------------------------------------\n\n/**\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmSchema<T> = ISchemaValidator<T>;\n\n/**\n * Schema node for a JSON `string`.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmStringSchema = ISchemaValidator<string>;\n\n/**\n * Schema node for a JSON `number` or `integer`.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmNumberSchema = ISchemaValidator<number>;\n\n/**\n * Schema node for a JSON `boolean`.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmBooleanSchema = ISchemaValidator<boolean>;\n\n/**\n * Schema node for a closed set of string literals (`enum`).\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmEnumSchema<T extends string> = ISchemaValidator<T>;\n\n/**\n * Wrapper marking a property as optional within an object schema.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmOptional<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S> | undefined>;\n\n/**\n * Schema node for a JSON `array`.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmArraySchema<S extends ISchemaValidator<unknown>> = ISchemaValidator<Static<S>[]>;\n\n/**\n * Schema node for a JSON `object`.\n * @deprecated Use `ISchemaValidator` instead.\n * @public\n */\nexport type ILlmObjectSchema<P extends ILlmProperties> = ISchemaValidator<ObjectStatic<P>>;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.1.0-33",
+  "version": "5.1.0-35",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -55,13 +55,13 @@
     "@rushstack/heft-node-rig": "2.11.27",
     "@microsoft/api-extractor": "^7.55.2",
     "typedoc": "~0.28.16",
-    "@fgv/ts-utils": "5.1.0-33",
-    "@fgv/ts-utils-jest": "5.1.0-33",
-    "@fgv/heft-dual-rig": "5.1.0-33",
-    "@fgv/typedoc-compact-theme": "5.1.0-33"
+    "@fgv/ts-utils": "5.1.0-35",
+    "@fgv/heft-dual-rig": "5.1.0-35",
+    "@fgv/typedoc-compact-theme": "5.1.0-35",
+    "@fgv/ts-utils-jest": "5.1.0-35"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-33"
+    "@fgv/ts-utils": "5.1.0-35"
   },
   "dependencies": {
     "luxon": "^3.7.2"