@flare-ts/lib 0.1.0

package/dist/schema/primitives/index.d.ts

@@ -0,0 +1,89 @@
+export { array } from "./array.js";
+export { bool } from "./bool.js";
+export { date } from "./date.js";
+export { enums } from "./enum.js";
+export { float } from "./float.js";
+export { int } from "./int.js";
+export { str } from "./str.js";
+export { text } from "./text.js";
+export { uuid } from "./uuid.js";
+/**
+ * JSON Schema fragment describing the constraints of a single primitive.
+ *
+ * Each primitive carries one of these on its `jsonSchema` property so the
+ * compiled serializer and {@link toJsonSchema} exporter can introspect it
+ * without re-deriving the shape.
+ */
+export type PrimitiveJsonSchema = Record<string, never> | {
+    type: "string";
+    format?: string;
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+} | {
+    type: "integer";
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: "number";
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "array";
+    items: PrimitiveJsonSchema;
+};
+/**
+ * Opaque reference to a primitive coercer.
+ *
+ * Carries the runtime metadata (`_type`, `_required`, `jsonSchema`) but no
+ * value-type information. Used wherever a collection of primitives is held
+ * without needing to invoke them or know their output type. To invoke a
+ * primitive and recover a typed value, use {@link TypedPrimitive}.
+ */
+export type Primitive = {
+    readonly _type: string;
+    readonly _required: boolean;
+    readonly jsonSchema: PrimitiveJsonSchema;
+};
+/**
+ * Carries the output type alongside the primitive coercer.
+ *
+ * Callable as `(v: string) => T`. Used as a leaf value inside schema
+ * descriptors and wherever the output type is needed.
+ *
+ * @template T The output type produced after coercion and validation.
+ */
+export type TypedPrimitive<T> = Primitive & {
+    (v: string): T;
+};
+/**
+ * Array-accepting primitive coercer that splits a comma-separated string or
+ * maps over an existing string array.
+ *
+ * @template T The element type produced after coercing each item.
+ */
+export type ArrayTypedPrimitive<T> = Primitive & {
+    (v: string | string[]): T[];
+};
+/**
+ * Wraps a primitive to accept missing or empty-string inputs, mapping them to `undefined`.
+ *
+ * @example
+ * ```ts
+ * const maybeInt = optional(int); // TypedPrimitive<number | undefined>
+ * ```
+ */
+export declare function optional<T>(primitive: TypedPrimitive<T>): TypedPrimitive<T | undefined>;
+/**
+ * Wraps a primitive so that missing or empty-string inputs produce `fallback` instead.
+ *
+ * @example
+ * ```ts
+ * const countOrZero = defaultTo(0, int.min(0));
+ * ```
+ */
+export declare function defaultTo<T>(fallback: T, primitive: TypedPrimitive<T>): TypedPrimitive<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/primitives/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schema/primitives/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GACrB;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACC;IACA,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACC;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACC;IACA,IAAI,EAAE,SAAS,CAAC;CACjB,GACC;IACA,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,mBAAmB,CAAC;CAC5B,CAAC;AAEJ;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,SAAS,GAAG;IAC1C,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,SAAS,GAAG;IAC/C,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,GAAG,SAAS,CAAC,CAUvF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAUzF"}

package/dist/schema/primitives/index.js

@@ -0,0 +1,44 @@
+import { array } from "./array.js";
+import { bool } from "./bool.js";
+import { date } from "./date.js";
+import { enums } from "./enum.js";
+import { float } from "./float.js";
+import { int } from "./int.js";
+import { str } from "./str.js";
+import { text } from "./text.js";
+import { uuid } from "./uuid.js";
+function optional(primitive) {
+  const optionalPrimitive = (v) => {
+    if (v === void 0) throw new TypeError("optional primitive received undefined");
+    if (v === "") return void 0;
+    return primitive(v);
+  };
+  optionalPrimitive._type = primitive._type;
+  optionalPrimitive._required = false;
+  optionalPrimitive.jsonSchema = primitive.jsonSchema;
+  return optionalPrimitive;
+}
+function defaultTo(fallback, primitive) {
+  const fn = (v) => {
+    if (v === void 0) throw new TypeError("defaultTo primitive received undefined");
+    if (v === "") return fallback;
+    return primitive(v);
+  };
+  fn._type = primitive._type;
+  fn._required = false;
+  fn.jsonSchema = primitive.jsonSchema;
+  return fn;
+}
+export {
+  array,
+  bool,
+  date,
+  defaultTo,
+  enums,
+  float,
+  int,
+  optional,
+  str,
+  text,
+  uuid
+};

package/dist/schema/primitives/int.d.ts

@@ -0,0 +1,24 @@
+import type { TypedPrimitive } from "./index.js";
+/**
+ * Integer primitive with optional chainable range constraints.
+ * Each builder method returns a new independent primitive so the original is never mutated.
+ */
+type IntPrimitive = TypedPrimitive<number> & {
+    /** Returns a new primitive that rejects values below `n`. */
+    min(n: number): IntPrimitive;
+    /** Returns a new primitive that rejects values above `n`. */
+    max(n: number): IntPrimitive;
+};
+/**
+ * Integer primitive. Rejects non-integer input and optionally enforces a range.
+ *
+ * @example
+ * ```ts
+ * int                 // any integer
+ * int.min(0)          // non-negative
+ * int.min(1).max(100) // bounded range
+ * ```
+ */
+export declare const int: IntPrimitive;
+export {};
+//# sourceMappingURL=int.d.ts.map

package/dist/schema/primitives/int.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"int.d.ts","sourceRoot":"","sources":["../../../src/schema/primitives/int.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,KAAK,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG;IAC3C,6DAA6D;IAC7D,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC7B,6DAA6D;IAC7D,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;CAC9B,CAAC;AAkDF;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,EAAE,YAAwB,CAAC"}

package/dist/schema/primitives/int.js

@@ -0,0 +1,43 @@
+const MAX_SAFE_INTEGER_DIGITS = String(Number.MAX_SAFE_INTEGER).length;
+function makeInt(config = {}) {
+  const { min, max } = config;
+  const fn = (v) => {
+    let i = 0;
+    let end = v.length;
+    while (i < end && v.charCodeAt(i) <= 32) i++;
+    while (end > i && v.charCodeAt(end - 1) <= 32) end--;
+    if (i >= end) throw new Error(`Expected integer, got "${v}"`);
+    let neg = false;
+    if (v.charCodeAt(i) === 45) {
+      neg = true;
+      i++;
+    }
+    if (i >= end) throw new Error(`Expected integer, got "${v}"`);
+    if (end - i > MAX_SAFE_INTEGER_DIGITS) throw new Error(`Value is not a safe integer: ${v}`);
+    let n = 0;
+    for (; i < end; i++) {
+      const d = v.charCodeAt(i) - 48;
+      if (d < 0 || d > 9) throw new Error(`Expected integer, got "${v}"`);
+      n = n * 10 + d;
+    }
+    const result = neg ? -n : n;
+    if (min !== void 0 && result < min) throw new Error(`Value too small: minimum is ${min}, got ${result}`);
+    if (max !== void 0 && result > max) throw new Error(`Value too large: maximum is ${max}, got ${result}`);
+    if (!Number.isSafeInteger(result)) throw new Error(`Value is not a safe integer: ${result}`);
+    return result;
+  };
+  fn._type = "int";
+  fn._required = true;
+  fn.jsonSchema = {
+    type: "integer",
+    ...config.min !== void 0 ? { minimum: config.min } : {},
+    ...config.max !== void 0 ? { maximum: config.max } : {}
+  };
+  fn.min = (n) => makeInt({ ...config, min: n });
+  fn.max = (n) => makeInt({ ...config, max: n });
+  return fn;
+}
+const int = makeInt();
+export {
+  int
+};

package/dist/schema/primitives/str.d.ts

@@ -0,0 +1,26 @@
+import type { TypedPrimitive } from "./index.js";
+/**
+ * String primitive with optional chainable length and pattern constraints.
+ * Each builder method returns a new independent primitive so the original is never mutated.
+ */
+type StringPrimitive = TypedPrimitive<string> & {
+    /** Returns a new primitive that rejects strings shorter than `n` characters. */
+    min(n: number): StringPrimitive;
+    /** Returns a new primitive that rejects strings longer than `n` characters. */
+    max(n: number): StringPrimitive;
+    /** Returns a new primitive that rejects strings not matching `regex`. */
+    pattern(regex: RegExp): StringPrimitive;
+};
+/**
+ * String primitive with optional chainable length and pattern constraints.
+ *
+ * @example
+ * ```ts
+ * string                            // any string
+ * string.min(3).max(50)             // length range
+ * string.pattern(/^\S+@\S+\..+$/)  // regex constraint
+ * ```
+ */
+export declare const str: StringPrimitive;
+export {};
+//# sourceMappingURL=str.d.ts.map

package/dist/schema/primitives/str.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"str.d.ts","sourceRoot":"","sources":["../../../src/schema/primitives/str.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,KAAK,eAAe,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG;IAC9C,gFAAgF;IAChF,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAChC,+EAA+E;IAC/E,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAChC,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC;CACzC,CAAC;AA+BF;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,EAAE,eAA2B,CAAC"}

package/dist/schema/primitives/str.js

@@ -0,0 +1,30 @@
+function makeStr(config = {}) {
+  const fn = (v) => {
+    if (config.min !== void 0 && v.length < config.min) {
+      throw new Error(`String too short: minimum length is ${config.min}, got ${v.length}`);
+    }
+    if (config.max !== void 0 && v.length > config.max) {
+      throw new Error(`String too long: maximum length is ${config.max}, got ${v.length}`);
+    }
+    if (config.pattern !== void 0 && !config.pattern.test(v)) {
+      throw new Error(`String does not match required pattern ${config.pattern}`);
+    }
+    return v;
+  };
+  fn._type = "string";
+  fn._required = true;
+  fn.jsonSchema = {
+    type: "string",
+    ...config.min !== void 0 ? { minLength: config.min } : {},
+    ...config.max !== void 0 ? { maxLength: config.max } : {},
+    ...config.pattern !== void 0 ? { pattern: config.pattern.source } : {}
+  };
+  fn.min = (n) => makeStr({ ...config, min: n });
+  fn.max = (n) => makeStr({ ...config, max: n });
+  fn.pattern = (regex) => makeStr({ ...config, pattern: regex });
+  return fn;
+}
+const str = makeStr();
+export {
+  str
+};

package/dist/schema/primitives/text.d.ts

@@ -0,0 +1,33 @@
+import type { TypedPrimitive } from "./index.js";
+/**
+ * Text primitive with optional chainable length and pattern constraints.
+ * Each builder method returns a new independent primitive so the original is never mutated.
+ */
+type TextPrimitive = TypedPrimitive<string> & {
+    /** Returns a new primitive that rejects strings shorter than `n` characters. */
+    min(n: number): TextPrimitive;
+    /** Returns a new primitive that rejects strings longer than `n` characters. */
+    max(n: number): TextPrimitive;
+    /** Returns a new primitive that rejects strings not matching `regex`. */
+    pattern(regex: RegExp): TextPrimitive;
+};
+/**
+ * Text primitive with optional chainable length and pattern constraints.
+ *
+ * Text is always escaped when serialized to JSON, so it is safe for untrusted input and
+ * can contain arbitrary Unicode characters including newlines. In contrast, the
+ * `string` primitive is intended for short single-line strings without special
+ * characters (e.g. names, titles) and is not escaped when serialized, so it will
+ * throw an error on the consumer side if the input contains special characters that
+ * would break JSON syntax.
+ *
+ * @example
+ * ```ts
+ * text                            // any text
+ * text.min(3).max(50)             // length range
+ * text.pattern(/^\S+@\S+\..+$/)  // regex constraint
+ * ```
+ */
+export declare const text: TextPrimitive;
+export {};
+//# sourceMappingURL=text.d.ts.map

package/dist/schema/primitives/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/schema/primitives/text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,KAAK,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG;IAC5C,gFAAgF;IAChF,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9B,+EAA+E;IAC/E,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAC9B,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC;CACvC,CAAC;AA+BF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,EAAE,aAA0B,CAAC"}

package/dist/schema/primitives/text.js

@@ -0,0 +1,30 @@
+function makeText(config = {}) {
+  const fn = (v) => {
+    if (config.min !== void 0 && v.length < config.min) {
+      throw new Error(`String too short: minimum length is ${config.min}, got ${v.length}`);
+    }
+    if (config.max !== void 0 && v.length > config.max) {
+      throw new Error(`String too long: maximum length is ${config.max}, got ${v.length}`);
+    }
+    if (config.pattern !== void 0 && !config.pattern.test(v)) {
+      throw new Error(`String does not match required pattern ${config.pattern}`);
+    }
+    return v;
+  };
+  fn._type = "text";
+  fn._required = true;
+  fn.jsonSchema = {
+    type: "string",
+    ...config.min !== void 0 ? { minLength: config.min } : {},
+    ...config.max !== void 0 ? { maxLength: config.max } : {},
+    ...config.pattern !== void 0 ? { pattern: config.pattern.source } : {}
+  };
+  fn.min = (n) => makeText({ ...config, min: n });
+  fn.max = (n) => makeText({ ...config, max: n });
+  fn.pattern = (regex) => makeText({ ...config, pattern: regex });
+  return fn;
+}
+const text = makeText();
+export {
+  text
+};

package/dist/schema/primitives/uuid.d.ts

@@ -0,0 +1,7 @@
+import type { TypedPrimitive } from "./index.js";
+/**
+ * UUID v4 primitive. Validates the canonical 8-4-4-4-12 hyphenated format.
+ */
+declare const uuid: TypedPrimitive<string>;
+export { uuid };
+//# sourceMappingURL=uuid.d.ts.map

package/dist/schema/primitives/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../../src/schema/primitives/uuid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;GAEG;AACH,QAAA,MAAM,IAAI,EAAE,cAAc,CAAC,MAAM,CAQhC,CAAC;AAEF,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/schema/primitives/uuid.js

@@ -0,0 +1,13 @@
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const uuid = Object.assign(
+  (v) => {
+    if (!UUID_V4_RE.test(v)) {
+      throw new Error(`Expected UUID v4, got "${v}"`);
+    }
+    return v;
+  },
+  { _type: "uuid", _required: true, jsonSchema: { type: "string", format: "uuid" } }
+);
+export {
+  uuid
+};

package/dist/schema/schema.d.ts

@@ -0,0 +1,167 @@
+import type { AnyDescriptorValue, InferSchemaShape } from "./internal/types/inference.js";
+import type { TypedPrimitive } from "./primitives/index.js";
+import { SCHEMA_BRAND } from "./internal/token/symbols.js";
+/** @internal One-item tuple used to declare an array schema token. */
+type TopLevelArraySchemaInput<T> = readonly [SchemaToken<T>];
+/** @internal One-item tuple used to declare a record schema token. */
+type TopLevelRecordSchemaInput<T> = readonly [{
+    $record: SchemaToken<T>;
+}];
+/**
+ * Single field-level parse error reported by {@link SchemaToken.safeParse}.
+ */
+export type FieldError = {
+    path: string;
+    message: string;
+    received: string;
+};
+/**
+ * Collection of field-level errors produced by a failed schema parse.
+ */
+export type ValidationError = {
+    fields: FieldError[];
+};
+/**
+ * Result of a schema parse operation.
+ *
+ * On success, `data` holds the parsed value typed as `T`. On failure, `error`
+ * holds a {@link ValidationError} describing which fields failed.
+ */
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ValidationError;
+};
+/**
+ * Any value that can appear in a JSON payload.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * JSON object with string keys and {@link JsonValue} values.
+ */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Runtime token representing a schema, with its value type erased.
+ *
+ * Used wherever a schema's identity is needed but not its output type, for
+ * example by the compiled serializer and JSON Schema exporter.
+ */
+export type OpaqueSchemaToken = {
+    readonly [SCHEMA_BRAND]: true;
+};
+/**
+ * Represents a type `T` that can be parsed from JSON input.
+ *
+ * Intentionally not a constructor: schema tokens cannot be extended. Use
+ * {@link model} when an extendable DTO base class is required.
+ */
+export type SchemaToken<T> = OpaqueSchemaToken & {
+    /** Parses raw input (JSON string, ArrayBuffer, or plain object) into `T`. */
+    safeParse(raw: ArrayBuffer | string | JsonValue): SafeParseResult<T>;
+    /** Marks this schema token as optional within a parent descriptor. */
+    optional(): SchemaToken<T>;
+};
+/**
+ * Extracts the union of all concrete discriminant values for key `K` across
+ * the members of the union type `T`.
+ *
+ * Useful when building generic utilities over discriminated schemas. Constrains
+ * the `branches` argument of the discriminated {@link schema} overload so every
+ * possible discriminant value must be handled.
+ */
+export type DiscriminantValues<T, K extends keyof T> = T extends Record<K, infer V extends string | number | symbol> ? V : never;
+/**
+ * For a union member of `T` whose discriminant key `K` equals `V`, produces
+ * the shape of that member with `K` omitted.
+ *
+ * Useful when building generic utilities over discriminated schemas.
+ */
+export type BranchShape<T, K extends keyof T, V extends DiscriminantValues<T, K>> = T extends Record<K, V> ? Omit<T, K> : never;
+/**
+ * Accepted value types for a single field within a schema descriptor.
+ *
+ * A field can be backed by either a {@link TypedPrimitive} coercer (e.g.
+ * `int`, `str`, `uuid`) or a nested {@link SchemaToken} produced by
+ * {@link schema}, enabling structural composition.
+ *
+ * @template T The TypeScript type the descriptor entry produces after parsing.
+ */
+export type DescriptorValue<T> = TypedPrimitive<T> | SchemaToken<T>;
+/**
+ * Creates a schema token that parses a JSON object field-by-field using the
+ * provided descriptor map.
+ *
+ * @example
+ * ```ts
+ * const UserSchema = schema({
+ *   id: uuid,
+ *   name: string,
+ * });
+ *
+ * // Manual parsing:
+ * const result = UserSchema.safeParse(requestBody);
+ *
+ * // Nested inside another schema:
+ * const EnvelopeSchema = schema({
+ *   user: UserSchema,
+ * });
+ * ```
+ */
+export declare function schema<D extends Record<string, AnyDescriptorValue>>(descriptor: D): SchemaToken<InferSchemaShape<D>>;
+/**
+ * Creates a schema token for a JSON array whose items are parsed by the
+ * provided nested schema token.
+ *
+ * The returned token can be used as a top-level parser or nested within
+ * another object schema descriptor.
+ *
+ * @example
+ * ```ts
+ * const WorldSchema = schema({ id: int, randomNumber: int });
+ * const WorldListSchema = schema([WorldSchema]);
+ *
+ * const BatchSchema = schema({
+ *   worlds: schema([WorldSchema]).optional(),
+ * });
+ * ```
+ */
+export declare function schema<T>(items: TopLevelArraySchemaInput<T>): SchemaToken<T[]>;
+/**
+ * Creates a schema token for a JSON object with dynamic string keys and uniform
+ * values, all validated by the provided nested schema token.
+ *
+ * Pass `[{ $record: ValueSchema }]` to use this overload.
+ *
+ * @example
+ * ```ts
+ * const TransportCfgSchema = schema({ level: enums(["debug", "info"]).optional() });
+ * const TransportsSchema = schema([{ $record: TransportCfgSchema }]);
+ * ```
+ */
+export declare function schema<T>(items: TopLevelRecordSchemaInput<T>): SchemaToken<Record<string, T>>;
+/**
+ * Creates a schema token that selects a branch descriptor based on the value
+ * of `discriminant` before parsing the remaining fields.
+ *
+ * @example
+ * ```ts
+ * const PetSchema = schema<Cat | Dog>('kind', {
+ *   cat: { lives: int },
+ *   dog: { breed: string },
+ * });
+ *
+ * ```
+ */
+export declare function schema<T extends object, _ extends "union", K extends keyof T & string = keyof T & string>(discriminant: K, branches: {
+    [V in DiscriminantValues<T, K>]: {
+        [F in keyof BranchShape<T, K, V>]: DescriptorValue<BranchShape<T, K, V>[F]>;
+    };
+}): SchemaToken<T>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema/schema.d.ts.map

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

package/dist/schema/schema.js

@@ -0,0 +1,74 @@
+import { arraySafeParse } from "./internal/parser/array.js";
+import { discriminatedSafeParse } from "./internal/parser/discriminated.js";
+import { flatSafeParse } from "./internal/parser/object.js";
+import { recordSafeParse } from "./internal/parser/record.js";
+import { makeOptionalSchemaToken } from "./internal/token/optionality.js";
+import { SCHEMA_BRAND, SCHEMA_DESCRIPTOR, SCHEMA_REQUIRED } from "./internal/token/symbols.js";
+function schema(descriptorOrDiscriminant, branches) {
+  if (Array.isArray(descriptorOrDiscriminant)) {
+    if (descriptorOrDiscriminant.length !== 1) {
+      throw new Error("Top-level array schemas must be declared with exactly one item schema.");
+    }
+    const first = descriptorOrDiscriminant[0];
+    if (first !== null && typeof first === "object" && "$record" in first) {
+      const valueSchema = first.$record;
+      const token3 = {
+        [SCHEMA_BRAND]: true,
+        [SCHEMA_REQUIRED]: true,
+        [SCHEMA_DESCRIPTOR]: descriptorOrDiscriminant,
+        optional() {
+          return makeOptionalSchemaToken(token3);
+        },
+        safeParse(raw) {
+          return recordSafeParse(raw, valueSchema);
+        }
+      };
+      return token3;
+    }
+    const items = descriptorOrDiscriminant;
+    const itemSchema = items[0];
+    const token2 = {
+      [SCHEMA_BRAND]: true,
+      [SCHEMA_REQUIRED]: true,
+      [SCHEMA_DESCRIPTOR]: items,
+      optional() {
+        return makeOptionalSchemaToken(token2);
+      },
+      safeParse(raw) {
+        return arraySafeParse(raw, itemSchema);
+      }
+    };
+    return token2;
+  }
+  if (typeof descriptorOrDiscriminant === "string" || typeof descriptorOrDiscriminant === "number" || typeof descriptorOrDiscriminant === "symbol") {
+    const discriminant = descriptorOrDiscriminant;
+    const token2 = {
+      [SCHEMA_BRAND]: true,
+      [SCHEMA_REQUIRED]: true,
+      [SCHEMA_DESCRIPTOR]: { discriminant, branches },
+      optional() {
+        return makeOptionalSchemaToken(token2);
+      },
+      safeParse(raw) {
+        return discriminatedSafeParse(raw, discriminant, branches);
+      }
+    };
+    return token2;
+  }
+  const descriptor = descriptorOrDiscriminant;
+  const token = {
+    [SCHEMA_BRAND]: true,
+    [SCHEMA_REQUIRED]: true,
+    [SCHEMA_DESCRIPTOR]: descriptor,
+    optional() {
+      return makeOptionalSchemaToken(token);
+    },
+    safeParse(raw) {
+      return flatSafeParse(raw, descriptor);
+    }
+  };
+  return token;
+}
+export {
+  schema
+};

package/dist/schema/symbol.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @internal
+ *
+ * Unique symbol stored as a static property on every class generated by
+ * {@link model}. Its value is the compiled JSON serializer produced eagerly
+ * at class-declaration time by {@link compileSerializer}.
+ *
+ * Consumers outside the lib package (e.g. the core transport layer) must
+ * access this symbol via {@link Symbol.for} with the same well-known key
+ * rather than importing this module directly.
+ *
+ * Well-known key: `"@flare-ts/schema/compiled-serializer"`
+ */
+export declare const COMPILED_SERIALIZER: unique symbol;
+//# sourceMappingURL=symbol.d.ts.map

package/dist/schema/symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.d.ts","sourceRoot":"","sources":["../../src/schema/symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAE/B,CAAC"}

package/dist/schema/symbol.js

@@ -0,0 +1,6 @@
+const COMPILED_SERIALIZER = /* @__PURE__ */ Symbol.for(
+  "@flare-ts/schema/compiled-serializer"
+);
+export {
+  COMPILED_SERIALIZER
+};