@ghostry/fabricator 0.0.7 → 0.0.9

package/dist/types/Primitive/string/Types.d.ts

@@ -1,5 +1,5 @@
 import type { Adaptations } from "../../Adapter/Types";
-import type { Bound, InputBound } from "../../Bound";
+import type { InputLength, Length } from "../../Bound";
 import type { Produce } from "../../Random/Types";
 import type { Adaptation, Kind, Meta, Produces } from "../../Types";
 import type { classes } from "./Constants";
@@ -25,17 +25,11 @@ export type CharacterClass = keyof typeof classes;
  */
 export type Composition = Partial<Record<CharacterClass, number>> | ReadonlyArray<[number, CharacterSource]>;
 export type InputWhereby = {
-    length: {
-        max: InputBound<number>;
-        min?: InputBound<number> | undefined;
-    };
+    length: InputLength;
     composition?: Composition;
 };
 export type Whereby = {
-    length: {
-        min: Bound<number>;
-        max: Bound<number>;
-    };
+    length: Length;
     composition?: Composition;
 };
 export type Fabricated = string;
@@ -54,8 +48,10 @@ export type JsonSchema = {
     pattern?: string;
 };
 /**
- * A length/composition, drawn via `whereby` — no natural bound to fuzz to, so
- * unlike `number`/`date` there's no bare form — optionally overridden by an
+ * A length and optional composition, drawn via `whereby`. There is no natural
+ * bound to fuzz a string to, so unlike `number`/`date` the builder itself has
+ * no bare form. `length` does: a bare count, or `{ min?, max, distribution? }`
+ * — the same {@link InputLength} `array` uses. Optionally overridden by an
  * opaque `as` production, carried alongside `whereby` rather than replacing it
  * (when `whereby` was already set) so a prior length/composition survives `as`
  * for future validation.

package/dist/types/Primitive/symbol/Schema.d.ts

@@ -1,6 +1,7 @@
 import { type AdaptationEntry } from "../../Adapter/Core";
 import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
 import type { Produce } from "../../Random/Types";
+import { type SatisfiesThis } from "../../Schema/Satisfies";
 import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
 /**
  * `$Meta` is generic (defaulting to the full `Meta` union) so builder return
@@ -15,6 +16,12 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
      * validation of `produce`) still has it to check against.
      */
     as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
+    /**
+     * Check that this schema's fabricated value type is assignable to `$Target`.
+     * Identity at runtime; the target is not carried into later chained calls —
+     * see `object/Schema.ts`'s `satisfies`.
+     */
+    satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Meta, $Adaptations>;
     /**
      * Override what this schema maps to in one or more external schema libraries
      * — see `string/Schema.ts`'s `adapt` for the full contract.

package/dist/types/Primitive/tuple/Schema.d.ts

@@ -1,6 +1,7 @@
 import { type AdaptationEntry } from "../../Adapter/Core";
 import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
 import type { Produce } from "../../Random/Types";
+import { type SatisfiesThis } from "../../Schema/Satisfies";
 import type { Core, Fabricated, Items } from "./Types";
 /**
  * Buildable `tuple` recipe: a fixed-length list of slot schemas, each
@@ -15,6 +16,12 @@ export interface Schema<$Items extends Items = Items, $Adaptations extends Adapt
      * validation of `produce`) still has it to check against.
      */
     as: (produce: Produce<Fabricated<$Items>>) => Schema<$Items, $Adaptations>;
+    /**
+     * Check that this schema's fabricated value type is assignable to `$Target`.
+     * Identity at runtime; the target is not carried into later chained calls —
+     * see `object/Schema.ts`'s `satisfies`.
+     */
+    satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Items>, $Target>): Schema<$Items, $Adaptations>;
     /**
      * Override what this schema maps to in one or more external schema libraries
      * — see `string/Schema.ts`'s `adapt` for the full contract.

package/dist/types/Primitive/undefinable/Schema.d.ts

@@ -1,6 +1,7 @@
 import { type AdaptationEntry } from "../../Adapter/Core";
 import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
 import type { Produce } from "../../Random/Types";
+import { type SatisfiesThis } from "../../Schema/Satisfies";
 import type { AnySchema } from "../../Schema/Types";
 import type { Core, Definition, Fabricated, Weights } from "./Types";
 /**
@@ -16,6 +17,12 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
      * does.
      */
     as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
+    /**
+     * Check that this schema's fabricated value type is assignable to `$Target`.
+     * Identity at runtime; the target is not carried into later chained calls —
+     * see `object/Schema.ts`'s `satisfies`.
+     */
+    satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
     /**
      * Reweight the built-in 50/50 roll. Keys are optional — an omitted key keeps
      * baseline weight `1`, the same weight the 50/50 split already uses — but

package/dist/types/Primitive/undefined/Schema.d.ts

@@ -1,12 +1,19 @@
 import { type AdaptationEntry } from "../../Adapter/Core";
 import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
-import type { Core, Meta as ThisMeta } from "./Types";
+import { type SatisfiesThis } from "../../Schema/Satisfies";
+import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
 /**
  * Nothing to configure (see `Types.ts`'s `Meta`), so `adapt` is this kind's
- * only builder method — an external library that spells "undefined" differently
+ * only mapping method — an external library that spells "undefined" differently
  * still needs a way to say so.
  */
 export interface Schema<$Adaptations extends Adaptations = {}> extends Core<ThisMeta, $Adaptations> {
+    /**
+     * Check that this schema's fabricated value type is assignable to `$Target`.
+     * Identity at runtime; the target is not carried into later chained calls —
+     * see `object/Schema.ts`'s `satisfies`.
+     */
+    satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Adaptations>;
     /**
      * Override what this schema maps to in one or more external schema libraries
      * — see `string/Schema.ts`'s `adapt` for the full contract.

package/dist/types/Schema/Core.d.ts

@@ -32,6 +32,19 @@ export declare function toSchema<$Kind extends string, $Meta extends PlainObject
     readonly [Produces]?: $Produces;
     readonly [Adaptation]?: $Adaptations;
 };
+/**
+ * The `[Kind]` a schema's fabricated value should be checked against with
+ * {@link violatesKind}. For most kinds that is its own `[Kind]`, but
+ * `object.compute` and `derive` only declare their value's shape, through
+ * `source` and `to`. Those resolve to that schema's kind, recursively, so a
+ * `to` that is itself a `derive` still reaches a checkable kind. Without this,
+ * an override of a derive-valued field would be checked against `"derive"`,
+ * which accepts anything.
+ */
+export declare function toValueKind(schema: {
+    [Kind]: SchemaKind;
+    [Meta]?: any;
+}): SchemaKind;
 /**
  * Whether `value`'s basic JS shape is compatible with `kind` (one of this
  * library's `[Kind]` literals, e.g. `"string"`, `"object"`, `"date"`). Stops at

package/dist/types/Schema/Satisfies.d.ts

@@ -0,0 +1,84 @@
+import type { NaiveFabricator } from "../Fabricator/Types";
+import type { Buildable, Produces } from "../Types";
+import type { ValueOf } from "./Types";
+/**
+ * The `this`-parameter constraint every kind's `.satisfies<$Target>()`
+ * intersects onto the receiver, so a mismatch names both sides on the call that
+ * failed — including a nested `T.object({ product: inner.satisfies<P>() })`,
+ * where the error lands on `inner` rather than the outer object.
+ *
+ * `$Produced` is each kind's own `Fabricated<…>` (or `Resolved<…>` for `derive`
+ * / `object.compute`, which have no `Fabricated` alias). A shared
+ * `ValueOf<this>` form errors in the same place but reports `"schema produces":
+ * any`, which is why each kind still names its own produced type. The check is
+ * wrapped in a 1-tuple so it does not distribute over unions: a bare `$Produced
+ * extends $Target ? unknown : Error` on `"x" | null` becomes `unknown | Error`,
+ * which is `unknown`, and `T.nullable(…).satisfies<string>()` would pass. Other
+ * signatures that were considered, and why they are not this:
+ *
+ * - A rest tuple `...check: D extends T ? [] : [error]` errors in the right place
+ *   but says "Expected 1 arguments, but got 0".
+ * - A return type `D extends T ? this : Error` is silent when the result is
+ *   unused, which is the typical `schema.satisfies<T>()` statement.
+ *
+ * The target is not carried forward: the method is typed as returning the
+ * kind's `Schema`, not a type that remembers `$Target`, so a later `.extend`
+ * that changes a field's type is not re-checked. Put `.satisfies` last to check
+ * the final shape. Carrying `$Target` on every `Schema` interface would add a
+ * type parameter to all 25 kinds, and `.as`'s contravariant parameter check is
+ * where a variance shift on those interfaces surfaces — `Types.ts`'s `ValueOf`
+ * note records that same check breaking from a constraint on `$Schema`. The
+ * return is `Schema`, not polymorphic `this`, because `T.date.past` /
+ * `T.number.integer` / `T.symbol` are `Schema & { whereby, … }` and a `this`
+ * return is not assignable into those extra members — same as `.as()`.
+ */
+export type SatisfiesThis<$Produced, $Target> = [$Produced] extends [$Target] ? unknown : {
+    "schema produces": $Produced;
+    "but target requires": $Target;
+};
+/**
+ * Shared `.satisfies()` body — identity at runtime. A regular function so
+ * `this` is the schema it was called on; an arrow would capture the module
+ * scope. Distinct from the standalone {@link satisfies} because the two
+ * signatures cannot share a name: this one is a method (`this`, return the
+ * receiver); that one is a statement (`buildable`, `void`).
+ */
+export declare function schemaSatisfies<$Receiver>(this: $Receiver): $Receiver;
+/**
+ * Whether `$Buildable` (a Schema or a built Fabricator) fabricates a value
+ * assignable to `$Target`. Resolves to `true` or to an object naming both
+ * sides, so asserting it (`true satisfies SatisfiedBy<…>`, or a local `type
+ * Expect<_ extends true> = true` as the test suites use) fails with a readable
+ * message rather than a bare `false`.
+ *
+ * Target first, so it reads as the sentence it asserts: `SatisfiedBy<Product,
+ * typeof schema>` — `Product` is satisfied by the schema. Swapping the
+ * parameters would name the opposite relationship.
+ *
+ * Assignable-to, not exact equality: extra fields pass. `T.optional` does not
+ * satisfy `note?: string` under `exactOptionalPropertyTypes` — it produces
+ * `note?: string | undefined` (present, present-as-`undefined`, or omitted).
+ * `T.omittable` produces `note?: string` and does.
+ */
+export type SatisfiedBy<$Target, $Buildable> = ValueOf<$Buildable> extends $Target ? true : {
+    produces: ValueOf<$Buildable>;
+    required: $Target;
+};
+/**
+ * Assert that `buildable` fabricates a value assignable to `$Target`. A
+ * statement, and a no-op at runtime — for a built Fabricator (which has no
+ * schema methods) and for a Schema the caller does not want to edit.
+ *
+ * `fabricate?: never` on the Schema arm is required. A built Fabricator has no
+ * `[Produces]`, and a type that lacks an optional property still matches `{
+ * readonly [Produces]?: $Target }` — the same trap `ValueOf` documents at
+ * `Types.ts`. Without the exclusion, a non-conforming Fabricator would pass the
+ * Schema arm unchecked. Ordered overloads do not replace this: overload
+ * resolution falls through a failing overload onto the next one, so a
+ * Fabricator rejected by `NaiveFabricator<$Target>` would still be accepted by
+ * the Schema arm.
+ */
+export declare function satisfies<$Target>(buildable: NaiveFabricator<$Target> | (Buildable & {
+    fabricate?: never;
+    readonly [Produces]?: $Target;
+})): void;

package/dist/types/Schema/Types.d.ts

@@ -1,4 +1,5 @@
 import type { Adaptations } from "../Adapter/Types";
+import type { NaiveFabricator } from "../Fabricator/Types";
 import type { Kind as SchemaKind } from "../Primitive";
 import type { Adaptation, Kind, Meta, Produces } from "../Types";
 import type { PlainObject } from "../Utility/Types";
@@ -26,6 +27,21 @@ export type AnySchema = {
  * (never assigned at runtime — see `DeepMerge`'s handling of optional-only keys
  * for why that matters).
  *
+ * A built Fabricator carries no `[Produces]` — its value type lives on
+ * `fabricate: () => $T` (`Fabricator/Types.ts`) — yet `toSchema` lets one stand
+ * anywhere a Schema is expected: an `array` element, an `object` field, a
+ * `tuple` slot, a `record` key or value, a wrapper's inner schema. So the
+ * `NaiveFabricator` branch comes **first**, reading `$T` straight off
+ * `fabricate`, and the `[Produces]` branch handles only what is left. That
+ * order is load-bearing: a conditional matching an _optional_ property still
+ * succeeds against a type that lacks it entirely (the same behavior
+ * `AdaptationsOf` has to work around in `Adapter/Types.ts`), so a Fabricator
+ * tested against `[Produces]` first matches, indexes a property it never had,
+ * and collapses to `unknown` — `T.array(built)` silently becoming `unknown[]`.
+ * `$Bindings` is not threaded into a Fabricator: it is already built, so any
+ * `self` inside it was resolved when it was. `Fabrication.types.test.ts`'s
+ * `NestedFabricatorAssertions` pin this.
+ *
  * `$Bindings` is threaded down into every composite kind's children (each
  * `Core` is an `interface` carrying an optional `bindings`, and forwards
  * `NonNullable<this["bindings"]>` into its own `[Produces]`). It is a
@@ -56,7 +72,7 @@ export type AnySchema = {
  *   deliberately omits it), and that shifts variance enough to break `.as`'s
  *   contravariant parameter check in `Fabrication.types.test.ts`.
  */
-export type ValueOf<$Schema, $Bindings extends unknown[] = []> = $Schema extends {
+export type ValueOf<$Schema, $Bindings extends unknown[] = []> = $Schema extends NaiveFabricator<infer $T> ? $T : $Schema extends {
     readonly [Produces]?: unknown;
 } ? Required<$Schema & {
     bindings: $Bindings;

package/dist/types/Types.d.ts

@@ -19,9 +19,10 @@ export declare const Layer: unique symbol;
  * already constructed for this node's nested schemas before handing them to the
  * kind's own `Fabricator()` factory. Every composite kind whose construction
  * receives already-dispatched Fabricators carries this: `object` (its `Fields`
- * map), `tuple` (`elements`, in slot order), `choice` (the dispatched options,
- * in `[Meta].items` order — weights stay in `[Meta]`), `array` (the single
- * shared `element`), `record` (`{ key, value }`), and each of
+ * map), `tuple` (`elements`, in slot order), `derive` (the dispatched `from`
+ * slots, in `[Meta].from` order), `choice` (the dispatched options, in
+ * `[Meta].items` order — weights stay in `[Meta]`), `array` (the single shared
+ * `element`), `record` (`{ key, value }`), and each of
  * `nullable`/`nullish`/`undefinable`/`object.omittable`/`object.optional` (the
  * single wrapped `source`).
  *

package/dist/types/index.d.ts

@@ -103,6 +103,15 @@ export type { Bound, InputBound } from "./Bound";
  * handed — so a caller writing either as a named function can name it.
  */
 export type { Stream } from "./Random/Types";
+/**
+ * Uniform pick and Fisher–Yates shuffle over a caller-held list, each taking
+ * the `Stream` a producer is already handed. Exported so a caller writing
+ * `.as(produce)`, `T.opaque`, or a `T.derive` resolver can draw from a list
+ * they already have — the same rationale as the `Stream` export. Prefer
+ * `T.enum` when the pick can be a schema: it is enumerable and path-keyed;
+ * these helpers are for the cases that cannot.
+ */
+export { sample, shuffle } from "./Distribution";
 /**
  * What every kind's `.as(produce)` producer is called with — a single curated
  * object rather than a positional argument list, so a caller writing the
@@ -140,6 +149,15 @@ export type { Fabrication } from "./Fabricator/Types";
  * Schema before it's built into a Fabricator.
  */
 export type { ValueOf } from "./Schema/Types";
+/**
+ * Check that a Schema or built Fabricator produces a value assignable to a
+ * supplied type — `.satisfies<T>()` on every kind's Schema is the main form;
+ * this function covers a built Fabricator (no schema methods) and a Schema the
+ * caller does not want to edit. `SatisfiedBy` is the type-only equivalent. See
+ * `Schema/Satisfies.ts`.
+ */
+export { satisfies } from "./Schema/Satisfies";
+export type { SatisfiedBy } from "./Schema/Satisfies";
 /**
  * `fabricator.trace`'s type — otherwise unnameable by a caller wanting to hold
  * onto one, the same reason `Stream` is exported above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostry/fabricator",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "license": "MIT",
   "description": "Fabricate typed data from composable schemas.",
   "keywords": [