@scalar/validation 0.1.0 → 0.2.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @scalar/validation@0.1.0 build /home/runner/work/scalar/scalar/packages/validation
+> @scalar/validation@0.2.0 build /home/runner/work/scalar/scalar/packages/validation
 > tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/validation
 
+## 0.2.0
+
+### Minor Changes
+
+- [#8600](https://github.com/scalar/scalar/pull/8600): feat: first class support for optional and intersection types
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -70,7 +70,7 @@ Use **`validate`** when you need a yes/no. Use **`coerce`** when you want a stab
 | `record(key, value)` | Plain object; keys and values match | `Record<…, …>` |
 | `object(props)` | Plain object; each key in `props` | Object of static fields |
 | `union([a, b, …])` | Matches any member | Union of branches |
-| `optional(s)` | Shorthand for `union([s, notDefined()])` | `Static<s> \| undefined` |
+| `optional(s)` | `undefined` or matches `s` | `Static<s> \| undefined`; in `object({ … })`, property becomes `key?: Static<s>` |
 | `lazy(() => schema)` | Defers schema (recursion) | Inferred from inner schema |
 | `evaluate(fn, schema)` | Runs `fn(value)` then validates `schema` | `Static<schema>` |
 

package/dist/coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAwDrC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EACrC,QAAQ,CAAC,EACT,OAAO,OAAO,EACd,QAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAiB,KAClD,MAAM,CAAC,CAAC,CA0FV,CAAA"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AA0FrC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EACrC,QAAQ,CAAC,EACT,OAAO,OAAO,EACd,QAAO,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAiB,KAClD,MAAM,CAAC,CAAC,CA6GV,CAAA"}

package/dist/coerce.js

@@ -1,5 +1,22 @@
 import { isObject } from './helpers/is-object.js';
 import { validate } from './validate.js';
+/**
+ * True when this property schema is only used to discriminate union branches
+ * (single literal, or a union of literals). No presence bonus when the value
+ * does not match — avoids ties like `type: literal('a')` vs `type: union([lit('b'), lit('c')])`.
+ */
+const isDiscriminatorProperty = (schema) => {
+    if (schema.type === 'optional') {
+        return isDiscriminatorProperty(schema.schema);
+    }
+    if (schema.type === 'literal') {
+        return true;
+    }
+    if (schema.type === 'union') {
+        return schema.schemas.length > 0 && schema.schemas.every(isDiscriminatorProperty);
+    }
+    return false;
+};
 /**
  * Computes a "score" indicating how well a value matches a schema,
  * used for picking the best branch in union coercion.
@@ -13,16 +30,23 @@ const scoreUnion = (schema, value) => {
         if (!isObject(value)) {
             return 0;
         }
-        // For each key in the schema's properties:
-        // - +10 if the value matches an explicit literal for the key.
-        // - +1 if the property exists (not literal match).
+        // Missing keys contribute 0 (including optional keys — matches prior union heuristics).
+        // Discriminator properties (`literal` or `union` of literals): recurse with scoreUnion;
+        // matching values get a high weight (×10) so `type: literal('A')` beats unrelated fields
+        // on another branch; mismatches score 0 (no "key present" tie-break).
+        // Other properties: scoreUnion plus +1 when the value fails validation so `{ a: null }`
+        // can still prefer the branch that declares `a`.
         return Object.keys(schema.properties).reduce((acc, key) => {
-            const exists = key in value;
-            const isLiteralMatch = schema.properties[key].type === 'literal' && value[key] === schema.properties[key].value;
-            if (isLiteralMatch) {
-                return acc + 10;
+            if (!(key in value)) {
+                return acc;
+            }
+            const propSchema = schema.properties[key];
+            const raw = value[key];
+            const base = scoreUnion(propSchema, raw);
+            if (isDiscriminatorProperty(propSchema)) {
+                return acc + (base > 0 ? base * 10 : 0);
             }
-            return acc + (exists ? 1 : 0);
+            return acc + (base > 0 ? base : 1);
         }, 0);
     }
     if (schema.type === 'array') {
@@ -33,10 +57,19 @@ const scoreUnion = (schema, value) => {
         // TODO: implement smarter scoring for records (just a placeholder for now)
         return isObject(value) ? 1 : 0;
     }
+    if (schema.type === 'optional') {
+        return value === undefined ? 1 : scoreUnion(schema.schema, value);
+    }
     if (schema.type === 'union') {
         // For a union, use the highest score among all sub-schemas
         return Math.max(...schema.schemas.map((schema) => scoreUnion(schema, value)));
     }
+    if (schema.type === 'intersection') {
+        if (schema.schemas.length === 0) {
+            return 1;
+        }
+        return schema.schemas.reduce((acc, sub) => acc + scoreUnion(sub, value), 0);
+    }
     if (schema.type === 'lazy') {
         // For a lazy schema, evaluate the inner schema and recurse
         return scoreUnion(schema.schema(), value);
@@ -108,6 +141,12 @@ export const coerce = (schema, value, cache = new WeakMap()) => {
     if (schema.type === 'notDefined') {
         return undefined;
     }
+    if (schema.type === 'optional') {
+        if (value === undefined) {
+            return undefined;
+        }
+        return coerce(schema.schema, value, cache);
+    }
     if (schema.type === 'array') {
         if (!Array.isArray(value)) {
             return [];
@@ -123,7 +162,16 @@ export const coerce = (schema, value, cache = new WeakMap()) => {
     if (schema.type === 'object') {
         const keys = Object.keys(schema.properties);
         const target = isObject(value) ? value : null;
-        return Object.fromEntries(keys.map((key) => [key, coerce(schema.properties[key], target?.[key], cache)]));
+        const entries = [];
+        for (const key of keys) {
+            const propSchema = schema.properties[key];
+            const raw = target?.[key];
+            if (propSchema.type === 'optional' && raw === undefined) {
+                continue;
+            }
+            entries.push([key, coerce(propSchema, raw, cache)]);
+        }
+        return Object.fromEntries(entries);
     }
     if (schema.type === 'union') {
         const branch = schema.schemas.reduce((acc, schema) => {
@@ -133,6 +181,9 @@ export const coerce = (schema, value, cache = new WeakMap()) => {
         // We need some way to pick one of the union values
         return coerce(branch.schema, value, cache);
     }
+    if (schema.type === 'intersection') {
+        return schema.schemas.reduce((acc, subSchema) => Object.assign(acc, coerce(subSchema, value, cache)), {});
+    }
     if (schema.type === 'literal') {
         return schema.value;
     }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { coerce } from './coerce.js';
-export { type Schema, any, array, boolean, evaluate, lazy, literal, notDefined, nullable, number, object, optional, record, string, union, } from './schema.js';
+export { type AnySchema, type ArraySchema, type BooleanSchema, type EvaluateSchema, type IntersectionSchema, type LazySchema, type LiteralSchema, type NotDefinedSchema, type NullableSchema, type NumberSchema, type ObjectSchema, type OptionalSchema, type RecordSchema, type Schema, type StringSchema, type UnionSchema, any, array, boolean, evaluate, intersection, lazy, literal, notDefined, nullable, number, object, optional, record, string, union, } from './schema.js';
+export { type GenerateTypesOptions, generateTypes } from './typegen.js';
 export type { Static } from './types.js';
 export { validate } from './validate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EACL,KAAK,MAAM,EACX,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,UAAU,EACV,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,MAAM,EACN,MAAM,EACN,KAAK,GACN,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,OAAO,EACP,UAAU,EACV,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,MAAM,EACN,MAAM,EACN,KAAK,GACN,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACpE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export { coerce } from './coerce.js';
-export { any, array, boolean, evaluate, lazy, literal, notDefined, nullable, number, object, optional, record, string, union, } from './schema.js';
+export { any, array, boolean, evaluate, intersection, lazy, literal, notDefined, nullable, number, object, optional, record, string, union, } from './schema.js';
+export { generateTypes } from './typegen.js';
 export { validate } from './validate.js';

package/dist/schema.d.ts

@@ -1,53 +1,76 @@
+/**
+ * Optional metadata for type generation and documentation.
+ * - typeName: Used as the exported TypeScript type name if valid.
+ * - typeComment: Adds a JSDoc comment to the generated type declaration.
+ */
+type Documentation = Partial<{
+    /** Adds a JSDoc comment to the generated type declaration. */
+    typeComment: string;
+    /** Used as the exported TypeScript type name if valid. */
+    typeName: string;
+}>;
 /** Schema for finite numeric values. {@link Static} resolves to `number`. */
 export type NumberSchema = {
     type: 'number';
-};
+} & Documentation;
 /** Schema for string values. {@link Static} resolves to `string`. */
 export type StringSchema = {
     type: 'string';
-};
+} & Documentation;
 /** Schema for boolean values. {@link Static} resolves to `boolean`. */
 export type BooleanSchema = {
     type: 'boolean';
-};
+} & Documentation;
 /** Schema for `null`. {@link Static} resolves to `null`. */
 export type NullableSchema = {
     type: 'nullable';
-};
+} & Documentation;
 /** Schema for a missing or omitted value. {@link Static} resolves to `undefined`. */
 export type NotDefinedSchema = {
     type: 'notDefined';
-};
+} & Documentation;
 /** Schema that accepts any value without narrowing. {@link Static} resolves to `any`. */
 export type AnySchema = {
     type: 'any';
-};
+} & Documentation;
 /** Schema for homogeneous lists. {@link Static} resolves to an array of the item static type. */
 export type ArraySchema<Item extends Schema> = {
     type: 'array';
     items: Item;
-};
+} & Documentation;
 /** Schema for key-value maps with uniform value shape. Keys are constrained to string or number schemas. */
 export type RecordSchema<Key extends StringSchema | NumberSchema | AnySchema, Value extends Schema> = {
     type: 'record';
     key: Key;
     value: Value;
-};
+} & Documentation;
 /** Schema for objects with a fixed set of named properties, each with its own schema. */
 export type ObjectSchema<Properties extends Record<string, Schema>> = {
     type: 'object';
     properties: Properties;
-};
+} & Documentation;
 /** Schema that matches if any member schema matches (discriminated union when literals or object tags differ). */
 export type UnionSchema<Schemas extends Schema[]> = {
     type: 'union';
     schemas: Schemas;
-};
+} & Documentation;
+/**
+ * Schema that accepts `undefined` or a value matching the inner schema.
+ * In {@link Static} and type generation, object properties use `key?:` instead of `T | undefined`.
+ */
+export type OptionalSchema<S extends Schema> = {
+    type: 'optional';
+    schema: S;
+} & Documentation;
+export type IntersectionSchema<Schemas extends readonly ObjectSchema<any>[]> = {
+    type: 'intersection';
+    schemas: Schemas;
+} & Documentation;
 /** Schema for a single exact constant (string, number, boolean, or bigint). {@link Static} is that literal type. */
 export type LiteralSchema<T extends string | number | boolean | bigint> = {
     type: 'literal';
     value: T;
-};
+} & Documentation;
 /**
  * Schema for self-referential or recursive types (such as trees or linked lists).
  * The `schema` property is a factory function returning a schema instance, allowing
@@ -66,20 +89,21 @@ export type EvaluateSchema<S extends Schema> = {
     expression: (value: unknown) => unknown;
     schema: S;
 };
-export type Schema = NumberSchema | StringSchema | BooleanSchema | NullableSchema | NotDefinedSchema | AnySchema | ArraySchema<any> | RecordSchema<any, any> | ObjectSchema<Record<string, any>> | UnionSchema<any[]> | LiteralSchema<any> | LazySchema<any> | EvaluateSchema<any>;
-declare const number: () => NumberSchema;
-declare const string: () => StringSchema;
-declare const boolean: () => BooleanSchema;
-declare const nullable: () => NullableSchema;
-declare const notDefined: () => NotDefinedSchema;
-declare const any: () => AnySchema;
-declare const array: <Item extends Schema>(items: Item) => ArraySchema<Item>;
-declare const record: <Key extends StringSchema | AnySchema, Value extends Schema>(key: Key, value: Value) => RecordSchema<Key, Value>;
-declare const object: <Properties extends Record<string, Schema>>(properties: Properties) => ObjectSchema<Properties>;
-declare const union: <Schemas extends Schema[]>(schemas: Schemas) => UnionSchema<Schemas>;
-declare const optional: <S extends Schema>(schema: S) => UnionSchema<(NotDefinedSchema | S)[]>;
+export type Schema = NumberSchema | StringSchema | BooleanSchema | NullableSchema | NotDefinedSchema | AnySchema | ArraySchema<any> | RecordSchema<any, any> | ObjectSchema<Record<string, any>> | UnionSchema<any[]> | OptionalSchema<any> | IntersectionSchema<readonly ObjectSchema<any>[]> | LiteralSchema<any> | LazySchema<any> | EvaluateSchema<any>;
+declare const number: (options?: Documentation) => NumberSchema;
+declare const string: (options?: Documentation) => StringSchema;
+declare const boolean: (options?: Documentation) => BooleanSchema;
+declare const nullable: (options?: Documentation) => NullableSchema;
+declare const notDefined: (options?: Documentation) => NotDefinedSchema;
+declare const any: (options?: Documentation) => AnySchema;
+declare const array: <Item extends Schema>(items: Item, options?: Documentation) => ArraySchema<Item>;
+declare const record: <Key extends StringSchema | AnySchema, Value extends Schema>(key: Key, value: Value, options?: Documentation) => RecordSchema<Key, Value>;
+declare const object: <Properties extends Record<string, Schema>>(properties: Properties, options?: Documentation) => ObjectSchema<Properties>;
+declare const union: <Schemas extends Schema[]>(schemas: Schemas, options?: Documentation) => UnionSchema<Schemas>;
+declare const intersection: <Schemas extends readonly ObjectSchema<any>[]>(schemas: Schemas, options?: Documentation) => IntersectionSchema<Schemas>;
+declare const optional: <S extends Schema>(schema: S, options?: Documentation) => OptionalSchema<S>;
 declare const literal: <Value extends string | number | boolean | bigint>(value: Value) => LiteralSchema<Value>;
 declare const lazy: <S extends () => Schema>(schema: S) => LazySchema<S>;
 declare const evaluate: <S extends Schema>(expression: (value: unknown) => unknown, schema: S) => EvaluateSchema<S>;
-export { number, string, boolean, nullable, notDefined, any, array, record, object, union, optional, literal, lazy, evaluate, };
+export { number, string, boolean, nullable, notDefined, any, array, record, object, union, intersection, optional, literal, lazy, evaluate, };
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,UAAU,CAAA;CACjB,CAAA;AAED,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,YAAY,CAAA;CACnB,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,KAAK,CAAA;CACZ,CAAA;AAED,iGAAiG;AACjG,MAAM,MAAM,WAAW,CAAC,IAAI,SAAS,MAAM,IAAI;IAC7C,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,IAAI,CAAA;CACZ,CAAA;AAED,4GAA4G;AAC5G,MAAM,MAAM,YAAY,CAAC,GAAG,SAAS,YAAY,GAAG,YAAY,GAAG,SAAS,EAAE,KAAK,SAAS,MAAM,IAAI;IACpG,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,GAAG,CAAA;IACR,KAAK,EAAE,KAAK,CAAA;CACb,CAAA;AAED,yFAAyF;AACzF,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;IACpE,IAAI,EAAE,QAAQ,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,kHAAkH;AAClH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI;IAClD,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,oHAAoH;AACpH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,IAAI;IACxE,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,CAAC,CAAA;CACT,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,MAAM,IAAI;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,CAAC,CAAA;CACV,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI;IAC7C,IAAI,EAAE,UAAU,CAAA;IAChB,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACvC,MAAM,EAAE,CAAC,CAAA;CACV,CAAA;AAED,MAAM,MAAM,MAAM,GACd,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,WAAW,CAAC,GAAG,CAAC,GAChB,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GACtB,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GACjC,WAAW,CAAC,GAAG,EAAE,CAAC,GAClB,aAAa,CAAC,GAAG,CAAC,GAClB,UAAU,CAAC,GAAG,CAAC,GACf,cAAc,CAAC,GAAG,CAAC,CAAA;AAEvB,QAAA,MAAM,MAAM,QAAO,YAEjB,CAAA;AAEF,QAAA,MAAM,MAAM,QAAO,YAEjB,CAAA;AAEF,QAAA,MAAM,OAAO,QAAO,aAElB,CAAA;AAEF,QAAA,MAAM,QAAQ,QAAO,cAEnB,CAAA;AAEF,QAAA,MAAM,UAAU,QAAO,gBAErB,CAAA;AAEF,QAAA,MAAM,GAAG,QAAO,SAEd,CAAA;AAEF,QAAA,MAAM,KAAK,GAAI,IAAI,SAAS,MAAM,EAAE,OAAO,IAAI,KAAG,WAAW,CAAC,IAAI,CAGhE,CAAA;AAEF,QAAA,MAAM,MAAM,GAAI,GAAG,SAAS,YAAY,GAAG,SAAS,EAAE,KAAK,SAAS,MAAM,EACxE,KAAK,GAAG,EACR,OAAO,KAAK,KACX,YAAY,CAAC,GAAG,EAAE,KAAK,CAIxB,CAAA;AAEF,QAAA,MAAM,MAAM,GAAI,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,UAAU,KAAG,YAAY,CAAC,UAAU,CAGzG,CAAA;AAEF,QAAA,MAAM,KAAK,GAAI,OAAO,SAAS,MAAM,EAAE,EAAE,SAAS,OAAO,KAAG,WAAW,CAAC,OAAO,CAG7E,CAAA;AAEF,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,0CAAkC,CAAA;AAE/E,QAAA,MAAM,OAAO,GAAI,KAAK,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,OAAO,KAAK,KAAG,aAAa,CAAC,KAAK,CAGnG,CAAA;AAEF,QAAA,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,MAAM,EAAE,QAAQ,CAAC,KAAG,UAAU,CAAC,CAAC,CAG5D,CAAA;AAEF,QAAA,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,EAAE,QAAQ,CAAC,KAAG,cAAc,CAAC,CAAC,CAIvG,CAAA;AAEF,OAAO,EACL,MAAM,EACN,MAAM,EACN,OAAO,EACP,QAAQ,EACR,UAAU,EACV,GAAG,EACH,KAAK,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,OAAO,EACP,IAAI,EACJ,QAAQ,GACT,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -1,39 +1,70 @@
-const number = () => ({
+const number = (options) => ({
     type: 'number',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const string = () => ({
+const string = (options) => ({
     type: 'string',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const boolean = () => ({
+const boolean = (options) => ({
     type: 'boolean',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const nullable = () => ({
+const nullable = (options) => ({
     type: 'nullable',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const notDefined = () => ({
+const notDefined = (options) => ({
     type: 'notDefined',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const any = () => ({
+const any = (options) => ({
     type: 'any',
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const array = (items) => ({
+const array = (items, options) => ({
     type: 'array',
     items,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const record = (key, value) => ({
+const record = (key, value, options) => ({
     type: 'record',
     key,
     value,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const object = (properties) => ({
+const object = (properties, options) => ({
     type: 'object',
     properties,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const union = (schemas) => ({
+const union = (schemas, options) => ({
     type: 'union',
     schemas,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
+});
+const intersection = (schemas, options) => ({
+    type: 'intersection',
+    schemas,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
+});
+const optional = (schema, options) => ({
+    type: 'optional',
+    schema,
+    typeName: options?.typeName,
+    typeComment: options?.typeComment,
 });
-const optional = (schema) => union([schema, notDefined()]);
 const literal = (value) => ({
     type: 'literal',
     value,
@@ -47,4 +78,4 @@ const evaluate = (expression, schema) => ({
     expression,
     schema,
 });
-export { number, string, boolean, nullable, notDefined, any, array, record, object, union, optional, literal, lazy, evaluate, };
+export { number, string, boolean, nullable, notDefined, any, array, record, object, union, intersection, optional, literal, lazy, evaluate, };

package/dist/typegen.d.ts

@@ -0,0 +1,25 @@
+import type { Schema } from './schema.js';
+export type GenerateTypesOptions = {
+    maxDepth?: number;
+    /**
+     * ISO 8601 timestamp printed in the autogenerated file banner.
+     * Defaults to the time of the `generateTypes` call when the banner is emitted.
+     */
+    generatedAt?: string;
+    /**
+     * When set to a valid TypeScript identifier, wraps all emitted `export type` declarations (and any
+     * trailing root type) in `export namespace Name { ... }` so consumers reference `Name.SomeType`.
+     */
+    namespace?: string;
+};
+/**
+ * Returns TypeScript for the schema: named `typeName` nodes become `export type` aliases (once each),
+ * referenced by name elsewhere. With no named nodes, returns a single inline type expression (same as before).
+ *
+ * When at least one named type is emitted, the result is prefixed with a banner stating the output is
+ * autogenerated and must not be edited manually, plus a generation timestamp.
+ *
+ * Pass `namespace` to wrap declarations in `export namespace … { … }`.
+ */
+export declare const generateTypes: (schema: Schema, options?: GenerateTypesOptions) => string;
+//# sourceMappingURL=typegen.d.ts.map

package/dist/typegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../src/typegen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAItC,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAcD;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,EAAE,UAAU,oBAAoB,KAAG,MAuB9E,CAAA"}

package/dist/typegen.js

@@ -0,0 +1,221 @@
+const DEFAULT_MAX_DEPTH = 10;
+/**
+ * Returns TypeScript for the schema: named `typeName` nodes become `export type` aliases (once each),
+ * referenced by name elsewhere. With no named nodes, returns a single inline type expression (same as before).
+ *
+ * When at least one named type is emitted, the result is prefixed with a banner stating the output is
+ * autogenerated and must not be edited manually, plus a generation timestamp.
+ *
+ * Pass `namespace` to wrap declarations in `export namespace … { … }`.
+ */
+export const generateTypes = (schema, options) => {
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const ctx = {
+        definitions: new Map(),
+        declarations: [],
+        inProgress: new Set(),
+    };
+    const root = emitSchema(schema, maxDepth, ctx, '');
+    if (ctx.declarations.length === 0) {
+        return root;
+    }
+    const declStrings = ctx.declarations.map(formatNamedDeclaration);
+    const body = declStrings.join('\n\n');
+    const lastDeclared = ctx.declarations.at(-1)?.name;
+    let content = lastDeclared === root ? body : `${body}\n\n${root}`;
+    const ns = options?.namespace;
+    if (ns && isValidTypeScriptIdentifier(ns)) {
+        content = wrapDeclarationsInNamespace(ns, content);
+    }
+    const generatedAt = options?.generatedAt ?? new Date().toISOString();
+    return `${formatAutogeneratedFileBanner(generatedAt)}${content}`;
+};
+const formatAutogeneratedFileBanner = (generatedAt) => `/**\n * This file is autogenerated. Do not edit it.\n *\n * Generated at: ${generatedAt}\n */\n\n`;
+const wrapDeclarationsInNamespace = (namespace, content) => {
+    const body = content
+        .split('\n')
+        .map((line) => (line === '' ? '' : `  ${line}`))
+        .join('\n');
+    return `export namespace ${namespace} {\n${body}\n}\n`;
+};
+const formatNamedDeclaration = (d) => {
+    const commentBlock = d.comment ? formatTypeCommentAsJsDoc(d.comment) : '';
+    const comment = commentBlock ? `${commentBlock}\n` : '';
+    return `${comment}export type ${d.name} = ${d.body}`;
+};
+/** Inline JSDoc for one line; multi-line comments use a newline after the opening delimiter and ` * ` on each line. */
+const formatTypeCommentAsJsDoc = (comment) => {
+    const lines = comment.split(/\r?\n/);
+    const trimmed = lines.map((line) => line.trim());
+    while (trimmed.length > 0 && trimmed[0] === '') {
+        trimmed.shift();
+    }
+    while (trimmed.length > 0 && trimmed.at(-1) === '') {
+        trimmed.pop();
+    }
+    if (trimmed.length === 0) {
+        return '';
+    }
+    if (trimmed.length === 1) {
+        return `/** ${trimmed[0]} */`;
+    }
+    const body = trimmed.map((line) => ` * ${line}`).join('\n');
+    return `/** \n${body}\n */`;
+};
+/** Prefixes each line of a JSDoc block with `indent` for object property comments. */
+const formatTypeCommentAsIndentedJsDoc = (indent, comment) => {
+    const doc = formatTypeCommentAsJsDoc(comment);
+    if (!doc) {
+        return '';
+    }
+    return doc
+        .split('\n')
+        .map((line) => `${indent}${line}`)
+        .join('\n');
+};
+const getTypeName = (schema) => {
+    if (schema.type === 'lazy' || schema.type === 'evaluate') {
+        return undefined;
+    }
+    const name = schema.typeName;
+    if (!name || !isValidTypeScriptIdentifier(name)) {
+        return undefined;
+    }
+    return name;
+};
+const getTypeComment = (schema) => {
+    if (schema.type === 'lazy' || schema.type === 'evaluate') {
+        return undefined;
+    }
+    if (schema.type === 'optional') {
+        return schema.typeComment ?? getTypeComment(schema.schema);
+    }
+    return schema.typeComment;
+};
+const isValidTypeScriptIdentifier = (name) => /^[$_A-Za-z][$_\w]*$/.test(name);
+const emitSchema = (schema, depth, ctx, braceIndent) => {
+    const name = getTypeName(schema);
+    if (name) {
+        if (ctx.definitions.has(name)) {
+            return name;
+        }
+        if (ctx.inProgress.has(name)) {
+            return name;
+        }
+        ctx.inProgress.add(name);
+        const body = structuralEmit(schema, depth, ctx, '');
+        ctx.inProgress.delete(name);
+        if (!ctx.definitions.has(name)) {
+            ctx.definitions.set(name, body);
+            ctx.declarations.push({
+                name,
+                body,
+                comment: getTypeComment(schema),
+            });
+        }
+        return name;
+    }
+    return structuralEmit(schema, depth, ctx, braceIndent);
+};
+const structuralEmit = (schema, depth, ctx, braceIndent) => {
+    if (depth <= 0) {
+        return 'any';
+    }
+    const next = depth - 1;
+    switch (schema.type) {
+        case 'number':
+            return 'number';
+        case 'string':
+            return 'string';
+        case 'boolean':
+            return 'boolean';
+        case 'nullable':
+            return 'null';
+        case 'notDefined':
+            return 'undefined';
+        case 'any':
+            return 'any';
+        case 'array': {
+            const item = emitSchema(schema.items, next, ctx, braceIndent);
+            return needsArrayItemParen(item) ? `(${item})[]` : `${item}[]`;
+        }
+        case 'record': {
+            const key = emitSchema(schema.key, next, ctx, braceIndent);
+            const value = emitSchema(schema.value, next, ctx, braceIndent);
+            return `Record<${key}, ${value}>`;
+        }
+        case 'object': {
+            const entries = Object.entries(schema.properties);
+            if (entries.length === 0) {
+                return '{}';
+            }
+            const keyIndent = `${braceIndent}  `;
+            const props = entries.map(([key, child]) => {
+                const tsKey = /^[$_a-zA-Z][$_\w]*$/.test(key) ? key : JSON.stringify(key);
+                const optionalProp = child.type === 'optional';
+                const valueSchema = optionalProp ? child.schema : child;
+                const value = emitSchema(valueSchema, next, ctx, keyIndent);
+                const propComment = getTypeComment(child);
+                const docBlock = propComment ? formatTypeCommentAsIndentedJsDoc(keyIndent, propComment) : '';
+                const propLine = optionalProp ? `${keyIndent}${tsKey}?: ${value};` : `${keyIndent}${tsKey}: ${value};`;
+                return docBlock ? `${docBlock}\n${propLine}` : propLine;
+            });
+            return `{\n${props.join('\n')}\n${braceIndent}}`;
+        }
+        case 'optional': {
+            const inner = emitSchema(schema.schema, next, ctx, braceIndent);
+            return `${wrapUnionMember(inner)} | undefined`;
+        }
+        case 'union':
+            if (schema.schemas.length === 0) {
+                return 'never';
+            }
+            return schema.schemas.map((s) => wrapUnionMember(emitSchema(s, next, ctx, braceIndent))).join(' | ');
+        case 'intersection':
+            if (schema.schemas.length === 0) {
+                return 'unknown';
+            }
+            return schema.schemas.map((s) => wrapIntersectionMember(emitSchema(s, next, ctx, braceIndent))).join(' & ');
+        case 'literal':
+            return literalToTs(schema.value);
+        case 'lazy':
+            return emitSchema(schema.schema(), next, ctx, braceIndent);
+        case 'evaluate':
+            return emitSchema(schema.schema, next, ctx, braceIndent);
+        default: {
+            const _exhaustive = schema;
+            return _exhaustive;
+        }
+    }
+};
+const literalToTs = (value) => {
+    if (typeof value === 'bigint') {
+        return `${value}n`;
+    }
+    return JSON.stringify(value);
+};
+const needsArrayItemParen = (t) => {
+    if (t === 'number' || t === 'string' || t === 'boolean' || t === 'null' || t === 'undefined' || t === 'any') {
+        return false;
+    }
+    // Union: `A | B[]` is `A | (B[])`; intersection: `A & B[]` is `A & (B[])`. Wrap the whole item type.
+    return t.includes(' | ') || t.includes(' & ');
+};
+const wrapUnionMember = (t) => {
+    if (t === 'number' || t === 'string' || t === 'boolean' || t === 'null' || t === 'undefined' || t === 'any') {
+        return t;
+    }
+    if (/^(?:-?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?|-?\d+n|"(?:[^"\\]|\\.)*"|true|false)$/.test(t)) {
+        return t;
+    }
+    if (/^[$_A-Za-z][$_\w]*$/.test(t)) {
+        return t;
+    }
+    return `(${t})`;
+};
+const wrapIntersectionMember = (t) => {
+    if (t.includes(' | ') || t.includes(' & ')) {
+        return `(${t})`;
+    }
+    return t;
+};