@raybase/record-mount 0.0.2 → 0.3.3

package/dist/testing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * A contract-conformant, in-memory record door — the dev-time half.
+ *
+ * It exists so that this package's own suite drives the real client
+ * against something that answers the wire contract's shapes, and so that a
+ * consuming app's tests can exercise its mount without a deployed Worker,
+ * a service binding, or a network. It is exported for exactly that.
+ *
+ * **What it is honest about.** It implements the contract's *shapes* — the
+ * result envelope, the closed taxonomy, the Row projection, `version()`,
+ * keyset paging, append idempotency by content hash, the ordering rule
+ * that `forbidden` outranks `not_found`. It is generic: no family, no id
+ * prefix and no lifecycle vocabulary is baked in, and every one of those
+ * is a hook with a documented generic default.
+ *
+ * **What it is not.** It is not the door. Bytes that this double accepts
+ * are not thereby proven acceptable to a deployed door — its frontmatter
+ * reader is this package's own, written to this package's own dialect, so
+ * a suite green against it is a builder-authored oracle for wire
+ * acceptance and nothing more. The real-door cross-check is a consumer-side
+ * act against the running door itself, and this double does not stand in
+ * for it. Its materialize path layout is its own invention (`family/id`),
+ * because the real one belongs to the consumer's substrate.
+ *
+ * ## Seam fidelity: why the default is a Proxy
+ *
+ * The double used to hand back a plain object that simply OMITTED
+ * `append`/`transition` for a read door. That is not how the production seam
+ * behaves, and the difference cost a real defect: a Cloudflare RPC
+ * service-binding stub answers EVERY property access with a callable, so
+ * every property-presence check the client made read `true` against a
+ * deployed read door while reading `false` against this fixture. The suite
+ * was green on a shape that does not exist in production — a self-authored
+ * oracle in its purest form.
+ *
+ * So by default the double presents as an RPC-faithful stub: a Proxy whose
+ * every property is a function, where calling one the underlying door does
+ * not carry rejects with a `TypeError` imitating the runtime's method-missing
+ * shape. Pass `rpc: false` for the plain object, which is the honest fixture
+ * for an in-process mount that really does hold a plain implementation.
+ *
+ * The imitation is an imitation, but its SHAPE is load-bearing: the client
+ * translates a `TypeError` only when its message carries the observed
+ * method-missing form — `does not implement` naming the verb — so the double
+ * reproduces that form. Do not pin the full string in a test as if it were
+ * workerd's contract; the wording is workerd's to change, and when it changes
+ * the client deliberately stops translating rather than guessing.
+ */
+import type { RecordDoorStub, RecordEnvelope, RecordErrorCode, RecordId } from "./contract.js";
+export type RecordDoorDoubleOptions = {
+    /** What `version()` serves. Set it to something else to drive the
+     *  client's fail-closed contract pin. */
+    contract?: string;
+    deployment?: string;
+    /** A read door has no `append`/`transition` at all. Default true. */
+    writable?: boolean;
+    /**
+     * Present as a Cloudflare RPC service-binding stub: a Proxy answering
+     * EVERY property access with a callable, where a verb this door does not
+     * carry rejects with a method-missing `TypeError` rather than being
+     * absent. **Default true** — this is what the production seam does, and a
+     * fixture that omits methods tests a shape no deployment has.
+     *
+     * Pass `false` for the plain object: the honest fixture for an in-process
+     * mount over a real implementation, where absence really is absence.
+     */
+    rpc?: boolean;
+    /**
+     * What `version()` declares in its `writes` field.
+     *
+     * Defaults to whatever `writable` says, which is what a door built after
+     * the field existed does. Pass `"omit"` to simulate an OLDER door that
+     * predates the declaration — the case where the client must stay
+     * `"unknown"` and translate whatever the runtime says instead.
+     */
+    declaredWrites?: boolean | "omit";
+    /**
+     * Answer every verb but `version()` with `invalid_binding`, as a door
+     * whose caller's props name no usable actor or namespace does.
+     * `version()` is the deliberate carve-out: the client's pin calls it
+     * before the contract is known, so it must answer on a props-less
+     * binding.
+     */
+    invalidBinding?: {
+        missing?: string[];
+        actor?: string;
+        served?: string[];
+    };
+    /** A handle built without a serializer refuses `transition` structurally. */
+    serializer?: boolean;
+    /**
+     * Family from an id — the real door's prefix-to-family map.
+     *
+     * Supply it and the double enforces that a body's `type` field equals the
+     * family its id's prefix names, exactly as the door does. Omit it and the
+     * double takes the family from the body's own `type`, falling back to the
+     * id's prefix.
+     *
+     * The default is deliberately NOT "prefix equals family": in a real
+     * corpus a prefix and a family name are different strings (`dec` names
+     * `decision`), so a default that demanded equality would refuse every
+     * realistic body and teach consumers to work around their own fixture.
+     */
+    familyOfId?: (id: string) => string | null;
+    /** The id shape. Default: `<prefix>-<yyyy-mm-dd>-<slug>`. */
+    idPattern?: RegExp;
+    /** The lifecycle frontmatter key per family, or null for a family that
+     *  is final at filing. Default: `"status"` for every family. */
+    lifecycleField?: (family: string) => string | null;
+    /** Whether an edge is legal. Default: every edge between non-empty
+     *  values is legal. A note (`expected === next`) never asks. */
+    isLegalTransition?: (family: string, from: string, to: string) => boolean;
+    /** The write grant. Default: every write is granted. */
+    canWrite?: (input: {
+        verb: "append" | "transition";
+        family: string;
+        id: RecordId;
+    }) => boolean;
+    /** How a Row's headline derives. Default: the body's first `# ` H1,
+     *  else its first non-blank prose line, else the id's slug. */
+    headline?: (input: {
+        envelope: RecordEnvelope;
+        body: string;
+    }) => string;
+    /** The refs edge. Default: the `refs` list field plus a scalar `ref`. */
+    refsOf?: (fields: Record<string, unknown>) => string[];
+    /** Entries per `materialize` page. Default 500, as the contract's. */
+    materializePageEntries?: number;
+};
+export type RecordDoorDouble = RecordDoorStub & {
+    /**
+     * Make the next call of one verb refuse with a code the double cannot
+     * reach on its own — `unavailable` when storage fails, `corrupt` when
+     * an integrity violation is discovered. One shot, consumed on use.
+     */
+    failNext(verb: keyof RecordDoorStub, error: {
+        code: RecordErrorCode;
+        detail?: Record<string, unknown>;
+        message?: string;
+    }): void;
+    /** Every id the double holds, in insertion order. */
+    ids(): RecordId[];
+};
+/** Build the door double. */
+export declare function createRecordDoorDouble(options?: RecordDoorDoubleOptions): RecordDoorDouble;
+/** An `env`-shaped object carrying the double under a binding name — what
+ *  `openRecordDoor({ env, binding })` reads. */
+export declare function recordDoorEnv<Name extends string>(binding: Name, door: RecordDoorStub): Record<Name, RecordDoorStub>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AASH,OAAO,KAAK,EAGV,cAAc,EACd,cAAc,EACd,eAAe,EAEf,QAAQ,EAMT,MAAM,eAAe,CAAC;AAYvB,MAAM,MAAM,uBAAuB,GAAG;IACpC;6CACyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC3E,6EAA6E;IAC7E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC3C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;oEACgE;IAChE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD;oEACgE;IAChE,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1E,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QACjB,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,EAAE,EAAE,QAAQ,CAAC;KACd,KAAK,OAAO,CAAC;IACd;mEAC+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;IACzE,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IACvD,sEAAsE;IACtE,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,cAAc,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjI,qDAAqD;IACrD,GAAG,IAAI,QAAQ,EAAE,CAAC;CACnB,CAAC;AAQF,6BAA6B;AAC7B,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAgXlB;AAuED;gDACgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,OAAO,EAAE,IAAI,EACb,IAAI,EAAE,cAAc,GACnB,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAE9B"}