@fougere/adapter-sql 0.6.0-alpha.0 → 0.8.0-alpha.0

package/README.md

@@ -3,9 +3,9 @@
 The SQL realization of the schema: the tables, the additive migration and the
 per-entity scoped storage. Four dialects — SQLite, PostgreSQL, MySQL, SQL Server.
 
-Validation judges, storage realizes: this storage decides nothing of its own — it applies
+Validation decides, storage realizes: this storage decides nothing of its own — it applies
 the `lifecycle` rules on the way in. The shape is still held on this path, twice: the
-DDL emits a `CHECK` for `oneOf`, `min` and `max`, and core's `StorageGuard` judges every
+DDL emits a `CHECK` for `oneOf`, `min` and `max`, and core's `StorageGuard` validates every
 write through the port. `storage.client` meets neither.
 
 ## Installation

package/dist/adapter.schema.json

@@ -0,0 +1,16 @@
+{
+    "type": "object",
+    "properties": {
+        "columnType": {
+            "type": "object",
+            "properties": {
+                "sqlite": { "type": "string" },
+                "pg": { "type": "string" },
+                "mysql": { "type": "string" },
+                "mssql": { "type": "string" }
+            },
+            "additionalProperties": false
+        }
+    },
+    "additionalProperties": false
+}

package/dist/check.d.ts

@@ -1,24 +1,4 @@
-/**
- * Shape → CHECK constraints.
- *
- * `oneOf`, `min`, `max` were declared on the field and read by the façade alone: a
- * handler writing through the storage put `status: 'brouillon'` in a column that declares
- * two values, and nothing said a word. The rule was in the schema; no one held it on
- * that path.
- *
- * So the storage learns what the shape already says. `validate` judges what a client
- * proposes; this holds what anyone writes — including us.
- *
- * Only the keywords a database can decide alone. `pattern` and `format` are left to
- * the façade: regex dialects diverge (POSIX here, PCRE there, nothing in SQLite
- * without an extension), and a constraint that means something different per engine
- * is worse than none.
- *
- * Every value is inlined with `sql.lit`, not bound: SQLite answers `parameters
- * prohibited in CHECK constraints`, and a constraint is part of the schema rather
- * than of a query. The values are the author's own literals — `oneOf('draft', …)`,
- * `max: 160` — never anything a request carried, and Kysely escapes them.
- */
+/** Shape → CHECK constraints. */
 import { type Expression, type SqlBool } from 'kysely';
 import type { ColumnDef } from './table.js';
 /** What a column's shape can be checked for, beyond its type. */
@@ -29,12 +9,7 @@ export interface ShapeBounds {
     minimum?: number;
     maximum?: number;
 }
-/**
- * The CHECK expression for one column, or nothing when its shape bounds nothing.
- *
- * A nullable column passes when it holds `null`: `NOT NULL` is the axis that decides
- * presence, and stacking the two would make `optional()` unwritable.
- */
+/** The CHECK expression for one column, or nothing when its shape bounds nothing. */
 export declare function checkFor(column: ColumnDef): Expression<SqlBool> | undefined;
 /** Read the bounds off a field's base shape — the keywords a database can decide. */
 export declare function boundsOf(shape: Record<string, unknown> | undefined): ShapeBounds | undefined;

package/dist/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAO,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAuB3E;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAU5F"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,OAAO,EAAO,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,SAAS,CAuB3E;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAU5F"}

package/dist/check.js

@@ -1,31 +1,6 @@
-/**
- * Shape → CHECK constraints.
- *
- * `oneOf`, `min`, `max` were declared on the field and read by the façade alone: a
- * handler writing through the storage put `status: 'brouillon'` in a column that declares
- * two values, and nothing said a word. The rule was in the schema; no one held it on
- * that path.
- *
- * So the storage learns what the shape already says. `validate` judges what a client
- * proposes; this holds what anyone writes — including us.
- *
- * Only the keywords a database can decide alone. `pattern` and `format` are left to
- * the façade: regex dialects diverge (POSIX here, PCRE there, nothing in SQLite
- * without an extension), and a constraint that means something different per engine
- * is worse than none.
- *
- * Every value is inlined with `sql.lit`, not bound: SQLite answers `parameters
- * prohibited in CHECK constraints`, and a constraint is part of the schema rather
- * than of a query. The values are the author's own literals — `oneOf('draft', …)`,
- * `max: 160` — never anything a request carried, and Kysely escapes them.
- */
+/** Shape → CHECK constraints. */
 import { sql } from 'kysely';
-/**
- * The CHECK expression for one column, or nothing when its shape bounds nothing.
- *
- * A nullable column passes when it holds `null`: `NOT NULL` is the axis that decides
- * presence, and stacking the two would make `optional()` unwritable.
- */
+/** The CHECK expression for one column, or nothing when its shape bounds nothing. */
 export function checkFor(column) {
     const bounds = column.bounds;
     if (!bounds)

package/dist/check.js.map

@@ -1 +1 @@
-{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,GAAG,EAAiC,MAAM,QAAQ,CAAC;AAY5D;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,KAAK,GAA0B,EAAE,CAAC;IAExC,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,kFAAkF;IAClF,+EAA+E;IAC/E,wEAAwE;IACxE,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,UAAU,GAAG,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7G,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,UAAU,GAAG,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7G,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjG,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEjG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAS,GAAG,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC;IAE9E,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAS,GAAG,GAAG,gBAAgB,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAC1E,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAA0C;IACjE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,IAAgB,CAAC;IAC7F,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,CAAU,EAAE,CAAC;QAC5E,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAW,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,OAAO,EAAE,GAAG,EAAiC,MAAM,QAAQ,CAAC;AAY5D,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,KAAK,GAA0B,EAAE,CAAC;IAExC,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,kFAAkF;IAClF,+EAA+E;IAC/E,wEAAwE;IACxE,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,UAAU,GAAG,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7G,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,UAAU,GAAG,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7G,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjG,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAS,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEjG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAS,GAAG,IAAI,QAAQ,KAAK,EAAE,CAAC,CAAC;IAE9E,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAS,GAAG,GAAG,gBAAgB,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAC1E,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAA0C;IACjE,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,KAAK,CAAC,IAAgB,CAAC;IAC7F,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,CAAU,EAAE,CAAC;QAC5E,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAW,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC"}

package/dist/crud.d.ts

@@ -1,19 +1,6 @@
-/**
- * SqlStorage — per-entity storage over Kysely, one implementation for every engine.
- *
- * Structurally matches @fougere/core's Storage (duck typed, no dep). There is
- * no generated table object: Kysely addresses tables and columns by name, so the
- * entity stays the only description. The field↔column mapping is explicit rather
- * than a global plugin — auth tables carry their own naming and must not be
- * rewritten behind the caller's back.
- *
- * `create` and `update` re-read the row instead of using `RETURNING`: the
- * contract is to hand back the COMPLETE row, including defaults realised by SQL.
- * That also makes the code identical on MySQL and SQL Server, which have no
- * `RETURNING` clause.
- */
+/** SqlStorage — per-entity storage over Kysely, one implementation for every engine. */
 import { type Kysely } from 'kysely';
-import { type SchemaView, type SchemaOrCard } from '@fougere/schema';
+import { type SchemaView } from '@fougere/schema';
 import { type DialectName } from './dialect.js';
 /** ListOptions — duplicated from @fougere/core to avoid a runtime dep. */
 interface ListOptions {
@@ -51,8 +38,8 @@ export declare class SqlStorage {
     private maxBindings;
     /** How this engine spells an upsert, or `false` when it cannot — see `Dialect.upsert`. */
     private upsertClause;
-    constructor(db: Kysely<any>, source: SchemaOrCard, tableName: string, selectFields?: Set<string>, dialect?: DialectName);
-    /** The Kysely instance this storage wraps — no judge sits behind it. See Storage.client. */
+    constructor(db: Kysely<any>, entity: SchemaView, tableName: string, selectFields?: Set<string>, dialect?: DialectName);
+    /** The Kysely instance this storage wraps — no validator sits behind it. See Storage.client. */
     get client(): Kysely<any>;
     /** Returns a scoped storage that restricts all read results to the fields of the given schema. */
     output(schema: SchemaView): SqlStorage;
@@ -64,60 +51,28 @@ export declare class SqlStorage {
     private toRow;
     /** Column keys → entity keys, and column values → the values the entity declares. */
     private fromRow;
-    /**
-     * Apply a primary-key filter (simple or composite).
-     *
-     * The key crosses to the column exactly like every other value — `whereAll` states
-     * the rule two lines below and this did not follow it. It cost nothing while every
-     * generated key was a string; a key that holds a Date (`primary(created())`) inserted
-     * fine and then failed its own re-read, with the row already persisted.
-     */
+    /** Apply a primary-key filter (simple or composite). */
     private wherePk;
     private whereAll;
+    /**
+     * What a bare value and a set could not say. Every comparison a criterion names is
+     * AND-ed, which is the rule two criteria already follow — `{ gte: 100, lte: 400 }` is
+     * one range, not two answers.
+     */
+    private compared;
     list(options?: ListOptions & SelectOption & {
         where?: Record<string, unknown>;
     }): Promise<ListResult<Record<string, unknown>>>;
     /**
-     * One query for N keys, never N queries — what every page-level read stands on:
-     * a computed field, a relation, a resolver on the other side of a wire.
-     *
-     * A composite key has no list form: it is refused by name rather than answering a
-     * partial result that reads as complete.
+     * One query for N keys, never N queries — what every page-level read stands on: a computed
+     * field, a relation, a resolver on the other side of a wire.
      */
     findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, Record<string, unknown>>>;
-    /**
-     * The other direction of a relation, in one query — see the port's `findAllByKeys`.
-     *
-     * The grouping key is read off the ROW rather than trusted from the request: a codec
-     * may write a value one way and read it back another, and a group keyed on the
-     * request's spelling would then be empty while the rows sit there.
-     */
+    /** The other direction of a relation, in one query — see the port's `findAllByKeys`. */
     findAllByKeys(field: string, keys: readonly string[], options?: SelectOption): Promise<Map<string, Record<string, unknown>[]>>;
-    /**
-     * Write the row, or make the existing one look like this — one statement.
-     *
-     * The gesture an import needs and the port did not have: `create` throws on the
-     * second run (`UNIQUE constraint failed`), so re-reading anything meant deleting
-     * first. Measured pulling 500 rows from an API twice.
-     *
-     * Both lifecycles are realized, each on the side it belongs to: `applyCreate` fills
-     * what a first write owes (a generated key, `created()`, a declared default) and
-     * `applyUpdate` stamps what every write owes (`updated()`). On conflict the key and
-     * the creation stamps are left alone — a row keeps the moment it appeared, whatever
-     * later overwrites say.
-     */
+    /** Write the row, or make the existing one look like this — one statement. */
     upsert(input: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown>>;
-    /**
-     * Upsert a whole page in one statement — what an import writes through.
-     *
-     * Row by row, 500 rows were 500 statements (measured pulling an API); the shape of
-     * an import is a page, so the write should be one too. Sliced like every other batch,
-     * but by rows × COLUMNS: a statement binds values, not rows, so the ceiling divides.
-     *
-     * Answers how many rows were written and not the rows themselves. `create` hands back
-     * the complete row because a caller acts on it; an import acts on none of them, and
-     * re-reading a page to satisfy a symmetry nobody uses would double the work.
-     */
+    /** Upsert a whole page in one statement — what an import writes through. */
     upsertAll(inputs: readonly Record<string, unknown>[], _options?: SelectOption): Promise<number>;
     /**
      * The COLUMNS a later write must not touch: the key, and a stamp that is create-only.
@@ -127,23 +82,14 @@ export declare class SqlStorage {
     findById(id: string | Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown> | undefined>;
     findBy(criteria: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown> | undefined>;
     findAllBy(criteria: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown>[]>;
-    /**
-     * One criteria object per statement — the oversized set is the one that splits.
-     *
-     * Only ONE criterion may be split: two split sets would need their cross product,
-     * which is a different query, so the second is refused rather than silently wrong.
-     */
+    /** One criteria object per statement — the oversized set is the one that splits. */
     private refuseOversized;
     private splitCriteria;
     create(input: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown>>;
     update(id: string | Record<string, unknown>, input: Record<string, unknown>, options?: SelectOption): Promise<Record<string, unknown>>;
     /**
-     * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the
-     * blank `Internal error` a caller used to get. The engine's own wording never travels:
-     * it names a table and a constraint, which is our schema and not the caller's business.
-     *
-     * Only the dialect can recognize it; this method knows no engine, which is the rule
-     * `dialect.ts` exists to keep.
+     * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the blank
+     * `Internal error` a caller used to get.
      */
     private refusal;
     delete(id: string | Record<string, unknown>): Promise<boolean>;
@@ -152,13 +98,7 @@ export interface StorageFactoryOptions {
     /** Override table name resolution. Default: camelCase → snake_case + 's'. */
     tableName?: (entityName: string) => string;
 }
-/**
- * Create a StorageFactory backed by Kysely — same call shape on every engine.
- *
- * ```ts
- * const app = await createApp({ createContainer, storageFactory: createStorageFactory(db) });
- * ```
- */
-export declare function createStorageFactory(db: Kysely<any>, options?: StorageFactoryOptions, dialect?: DialectName): (entity: SchemaOrCard, name: string) => SqlStorage;
+/** Create a StorageFactory backed by Kysely — same call shape on every engine. */
+export declare function createStorageFactory(db: Kysely<any>, options?: StorageFactoryOptions, dialect?: DialectName): (entity: SchemaView, name: string) => SqlStorage;
 export {};
 //# sourceMappingURL=crud.d.ts.map

package/dist/crud.d.ts.map

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

package/dist/crud.js

@@ -1,34 +1,14 @@
 import { Lifecycle, Role } from '@fougere/schema';
-/**
- * SqlStorage — per-entity storage over Kysely, one implementation for every engine.
- *
- * Structurally matches @fougere/core's Storage (duck typed, no dep). There is
- * no generated table object: Kysely addresses tables and columns by name, so the
- * entity stays the only description. The field↔column mapping is explicit rather
- * than a global plugin — auth tables carry their own naming and must not be
- * rewritten behind the caller's back.
- *
- * `create` and `update` re-read the row instead of using `RETURNING`: the
- * contract is to hand back the COMPLETE row, including defaults realised by SQL.
- * That also makes the code identical on MySQL and SQL Server, which have no
- * `RETURNING` clause.
- */
+/** SqlStorage — per-entity storage over Kysely, one implementation for every engine. */
 import { sql } from 'kysely';
-import { applyCreate, applyUpdate, schemaOf } from '@fougere/schema';
+import { applyCreate, applyUpdate } from '@fougere/schema';
 import { toTable, toTableName } from './table.js';
 import { resolveDialect } from './dialect.js';
 // The contract entry and not the main one: `FougereError` crosses a process boundary and
 // lives there for that reason, and this package must not drag the boot to raise one.
-import { FougereError, ErrorCode } from '@fougere/core/contract';
+import { comparisonOf, comparisonsIn, ErrorCode, FougereError } from '@fougere/core/contract';
 import { codecsOf } from './values.js';
-/**
- * The primary key, read off the role axis.
- *
- * Used to answer "what identifies a row" — where to point a WHERE, what a cursor
- * carries. The generated ids and managed timestamps that used to be computed here
- * moved to `applyCreate`/`applyUpdate` (`@fougere/schema`): nothing in them was about
- * SQL, and every other storage was re-deriving them from scratch.
- */
+/** The primary key, read off the role axis. */
 function analyzeFields(entity) {
     const pkNames = Object.entries(entity.getFields())
         .filter(([, field]) => Role.of(field).isPrimary)
@@ -78,16 +58,12 @@ export class SqlStorage {
     maxBindings;
     /** How this engine spells an upsert, or `false` when it cannot — see `Dialect.upsert`. */
     upsertClause;
-    constructor(db, source, tableName, selectFields, dialect = 'sqlite') {
+    constructor(db, entity, tableName, selectFields, dialect = 'sqlite') {
         this.db = db;
         const resolved = resolveDialect(dialect);
         this.dialect = resolved;
         this.maxBindings = resolved.maxBindings;
         this.upsertClause = resolved.upsert;
-        // Normalized once: the table projection and the axis analysis below both read the
-        // schema, and a card handed to each separately would be rebuilt twice into two
-        // unrelated field objects. Past this line nothing knows which form arrived.
-        const entity = schemaOf(source);
         this.table = toTable(tableName, entity);
         for (const column of this.table.columns) {
             this.toColumn.set(column.field, column.name);
@@ -98,7 +74,7 @@ export class SqlStorage {
         this.fields = entity.getFields();
         this.selectFields = selectFields;
     }
-    /** The Kysely instance this storage wraps — no judge sits behind it. See Storage.client. */
+    /** The Kysely instance this storage wraps — no validator sits behind it. See Storage.client. */
     get client() {
         return this.db;
     }
@@ -136,18 +112,11 @@ export class SqlStorage {
         }
         return data;
     }
-    /**
-     * Apply a primary-key filter (simple or composite).
-     *
-     * The key crosses to the column exactly like every other value — `whereAll` states
-     * the rule two lines below and this did not follow it. It cost nothing while every
-     * generated key was a string; a key that holds a Date (`primary(created())`) inserted
-     * fine and then failed its own re-read, with the row already persisted.
-     */
+    /** Apply a primary-key filter (simple or composite). */
     wherePk(query, id) {
         if (this.pk.isComposite) {
-            const obj = id;
-            return this.pk.names.reduce((q, name) => q.where(this.column(name), '=', this.write(name, obj[name])), query);
+            const composite = id;
+            return this.pk.names.reduce((q, name) => q.where(this.column(name), '=', this.write(name, composite[name])), query);
         }
         const name = this.pk.names[0];
         return query.where(this.column(name), '=', this.write(name, id));
@@ -161,9 +130,42 @@ export class SqlStorage {
     // dual already went through this same door. An empty set matches nothing, said in
     // SQL rather than by returning the whole table.
     whereAll(query, criteria) {
-        return Object.entries(criteria).reduce((q, [key, value]) => Array.isArray(value)
-            ? q.where(this.column(key), 'in', [...new Set(value)].map((v) => this.write(key, v)))
-            : q.where(this.column(key), '=', this.write(key, value)), query);
+        return Object.entries(criteria).reduce((q, [key, value]) => {
+            const comparison = comparisonOf(this.fields[key], value);
+            if (comparison)
+                return this.compared(q, key, comparison);
+            return Array.isArray(value)
+                ? q.where(this.column(key), 'in', [...new Set(value)].map((v) => this.write(key, v)))
+                : q.where(this.column(key), '=', this.write(key, value));
+        }, query);
+    }
+    /**
+     * What a bare value and a set could not say. Every comparison a criterion names is
+     * AND-ed, which is the rule two criteria already follow — `{ gte: 100, lte: 400 }` is
+     * one range, not two answers.
+     */
+    compared(query, key, comparison) {
+        const column = this.column(key);
+        const bound = (value) => this.write(key, value);
+        return comparisonsIn(comparison).reduce((q, [name, value]) => {
+            switch (name) {
+                case 'gte': return q.where(column, '>=', bound(value));
+                case 'lte': return q.where(column, '<=', bound(value));
+                case 'gt': return q.where(column, '>', bound(value));
+                case 'lt': return q.where(column, '<', bound(value));
+                case 'ne': return q.where(column, '!=', bound(value));
+                case 'contains': return q.where(column, 'like', `%${String(value)}%`);
+                case 'notIn': {
+                    const values = [...new Set(value)].map(bound);
+                    return values.length ? q.where(column, 'not in', values) : q;
+                }
+                case 'isNull': return q.where(column, value ? 'is' : 'is not', null);
+                case 'between': {
+                    const [low, high] = value;
+                    return q.where(column, '>=', bound(low)).where(column, '<=', bound(high));
+                }
+            }
+        }, query);
     }
     async list(options) {
         let query = this.db.selectFrom(this.table.name).selectAll();
@@ -224,11 +226,8 @@ export class SqlStorage {
         return sel ? pickList(result, sel) : result;
     }
     /**
-     * One query for N keys, never N queries — what every page-level read stands on:
-     * a computed field, a relation, a resolver on the other side of a wire.
-     *
-     * A composite key has no list form: it is refused by name rather than answering a
-     * partial result that reads as complete.
+     * One query for N keys, never N queries — what every page-level read stands on: a computed
+     * field, a relation, a resolver on the other side of a wire.
      */
     async findByKeys(ids, options) {
         if (this.pk.isComposite) {
@@ -254,13 +253,7 @@ export class SqlStorage {
         }
         return found;
     }
-    /**
-     * The other direction of a relation, in one query — see the port's `findAllByKeys`.
-     *
-     * The grouping key is read off the ROW rather than trusted from the request: a codec
-     * may write a value one way and read it back another, and a group keyed on the
-     * request's spelling would then be empty while the rows sit there.
-     */
+    /** The other direction of a relation, in one query — see the port's `findAllByKeys`. */
     async findAllByKeys(field, keys, options) {
         const grouped = new Map();
         if (keys.length === 0)
@@ -268,27 +261,15 @@ export class SqlStorage {
         const rows = await this.findAllBy({ [field]: [...keys] }, options);
         for (const row of rows) {
             const key = String(row[field]);
-            const held = grouped.get(key);
-            if (held)
-                held.push(row);
+            const bucket = grouped.get(key);
+            if (bucket)
+                bucket.push(row);
             else
                 grouped.set(key, [row]);
         }
         return grouped;
     }
-    /**
-     * Write the row, or make the existing one look like this — one statement.
-     *
-     * The gesture an import needs and the port did not have: `create` throws on the
-     * second run (`UNIQUE constraint failed`), so re-reading anything meant deleting
-     * first. Measured pulling 500 rows from an API twice.
-     *
-     * Both lifecycles are realized, each on the side it belongs to: `applyCreate` fills
-     * what a first write owes (a generated key, `created()`, a declared default) and
-     * `applyUpdate` stamps what every write owes (`updated()`). On conflict the key and
-     * the creation stamps are left alone — a row keeps the moment it appeared, whatever
-     * later overwrites say.
-     */
+    /** Write the row, or make the existing one look like this — one statement. */
     async upsert(input, options) {
         if (this.upsertClause === false) {
             throw new Error(`${this.table.name}.upsert(): this engine has no upsert clause — read with findById ` +
@@ -313,17 +294,7 @@ export class SqlStorage {
             : data[this.pk.names[0]];
         return (await this.findById(id, options));
     }
-    /**
-     * Upsert a whole page in one statement — what an import writes through.
-     *
-     * Row by row, 500 rows were 500 statements (measured pulling an API); the shape of
-     * an import is a page, so the write should be one too. Sliced like every other batch,
-     * but by rows × COLUMNS: a statement binds values, not rows, so the ceiling divides.
-     *
-     * Answers how many rows were written and not the rows themselves. `create` hands back
-     * the complete row because a caller acts on it; an import acts on none of them, and
-     * re-reading a page to satisfy a symmetry nobody uses would double the work.
-     */
+    /** Upsert a whole page in one statement — what an import writes through. */
     async upsertAll(inputs, _options) {
         if (this.upsertClause === false) {
             throw new Error(`${this.table.name}.upsertAll(): this engine has no upsert clause — write the rows ` +
@@ -391,12 +362,7 @@ export class SqlStorage {
         }
         return out;
     }
-    /**
-     * One criteria object per statement — the oversized set is the one that splits.
-     *
-     * Only ONE criterion may be split: two split sets would need their cross product,
-     * which is a different query, so the second is refused rather than silently wrong.
-     */
+    /** One criteria object per statement — the oversized set is the one that splits. */
     refuseOversized(criteria, op) {
         for (const [key, value] of Object.entries(criteria)) {
             if (!Array.isArray(value) || new Set(value).size <= this.maxBindings)
@@ -425,7 +391,7 @@ export class SqlStorage {
         // writer that is not us, the way a CHECK does; nothing depends on it any more.
         const data = applyCreate(this.fields, input);
         await this.refusal(() => this.db.insertInto(this.table.name).values(this.toRow(data)).execute());
-        // Contract: create returns the COMPLETE row (validation judges absence, it
+        // Contract: create returns the COMPLETE row (validation validates absence, it
         // never fills) — re-read so SQL-realised defaults appear. Same move as update().
         const id = this.pk.isComposite
             ? Object.fromEntries(this.pk.names.map((n) => [n, data[n]]))
@@ -444,12 +410,8 @@ export class SqlStorage {
         return sel ? pick(result, sel) : result;
     }
     /**
-     * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the
-     * blank `Internal error` a caller used to get. The engine's own wording never travels:
-     * it names a table and a constraint, which is our schema and not the caller's business.
-     *
-     * Only the dialect can recognize it; this method knows no engine, which is the rule
-     * `dialect.ts` exists to keep.
+     * A duplicate is an ANSWER, not a failure — so it leaves as `CONFLICT` and not as the blank
+     * `Internal error` a caller used to get.
      */
     async refusal(write) {
         try {
@@ -473,13 +435,7 @@ export class SqlStorage {
         return true;
     }
 }
-/**
- * Create a StorageFactory backed by Kysely — same call shape on every engine.
- *
- * ```ts
- * const app = await createApp({ createContainer, storageFactory: createStorageFactory(db) });
- * ```
- */
+/** Create a StorageFactory backed by Kysely — same call shape on every engine. */
 export function createStorageFactory(db, options, dialect = 'sqlite') {
     const resolve = options?.tableName ?? toTableName;
     return (entity, name) => new SqlStorage(db, entity, resolve(name), undefined, dialect);