cogsbox-shape 0.5.206 → 0.5.208

package/README.md

@@ -307,6 +307,28 @@ schema({ ... })
 
 **Note**: `parsePatchForDb` uses the base schema (without refinement) since partial data may not satisfy cross-field rules.
 
+### Schemas vs Validators
+
+Each box entry exposes two sets of Zod schemas:
+
+- **`schemas`** — plain `ZodObject` shapes. Always composable with `.pick()`, `.omit()`, `.partial()`, etc. Use these for form field extraction, type inference, and partial validation.
+- **`validators`** — schema + refinements. These are `ZodEffects` when `.refine()` is used, otherwise the same `ZodObject`. Use these for full validation that enforces cross-field rules.
+
+```typescript
+const box = createSchemaBox({ events }, { events: {} });
+
+// Base schema — always a ZodObject, always composable
+box.events.schemas.client.pick({ startDate: true, endDate: true }); // works!
+
+// Validator — enforces refine rules
+box.events.validators.client.safeParse(data); // runs cross-field checks
+
+// Internal transforms use validators automatically
+box.events.transforms.parseForDb(data); // uses validator.server
+```
+
+Why the split? After `.refine()`, Zod wraps the schema in `ZodEffects`, which loses `.shape`, `.pick()`, `.omit()`, and `.partial()`. By keeping the base schema separate from refinements, you can always compose the shape while still enforcing cross-field rules when needed.
+
 ### Schema Object Structure
 
 The returned schema object has a clear separation of concerns:
@@ -314,16 +336,17 @@ The returned schema object has a clear separation of concerns:
 ```typescript
 const schema = createSchema(mySchema);
 
-schema.schemas; // { sql, client, clientChecked, server } — Zod schemas
+schema.schemas; // { sql, client, clientChecked, server } — ZodObject shapes (composable)
+schema.validators; // { sql, client, clientChecked, server } — with refinements enforced
 schema.transforms; // { toClient, toDb, parseForDb, parseFromDb } — transformations
 schema.defaults; // Default values for forms
-schema.generateDefaults; // Function to generate fresh client defaults (executes randomizers)
+schema.generateDefaults; // Function to generate fresh client defaults (executes randomizers)
 schema.pk; // Primary key field names
 schema.clientPk; // Client-side primary key field names
 schema.isClientRecord; // Function to check if a record is client-created
 schema.deriveDependencies; // Derive function dependencies ({ [field]: string[] })
 schema.refineInfo; // Refinement info ({ groups: RefineEntry[], fieldToGroup: Record<string, number[]> })
-```
+```
 
 ## Using Schemas
 
@@ -364,8 +387,11 @@ const { toClient, toDb, parseForDb, parseFromDb } = schema.transforms;
 const [data, setData] = useState(generateDefaults());
 // { id: "new_a1b2c3d4", name: "", email: "", isActive: true }
 
-// Validate explicitly
-const result = server.safeParse(data);
+// Validate explicitly (use validators for refinement enforcement)
+const result = schema.validators.server.safeParse(data);
+
+// Or use the base schema for shape operations
+const pickedSchema = schema.schemas.server.pick({ email: true, age: true });
 
 // Or handle validation & transformation in a single step!
 const safeDbRow = parseForDb(data);
@@ -469,6 +495,22 @@ const user = await userView.findById(1);
 // user.posts is loaded and validated as part of the view shape
 ```
 
+Cloudflare D1 uses the same SQLite schema dialect with a D1 connection helper:
+
+```typescript
+import { connect } from "cogsbox-shape/db";
+import { createD1Db } from "cogsbox-shape/db/cloudflare-d1";
+
+export default {
+  async fetch(_request, env) {
+    const db = createD1Db(env.DB);
+    const bx = connect(box, db);
+
+    return Response.json(await bx.users.findMany());
+  },
+};
+```
+
 Use `insert(data).ids()` when you only need the database identity, or `insert(data).full()` when you want optimistic client IDs reconciled back into the submitted client object. `create()` is kept as an alias for older code; prefer `insert()` in new code.
 
 ### 5. Nested Defaults and Form Definitions (`defaultsDefinition`)

package/cogsbox-shape-db/dist/cloudflare-d1/d1-driver.d.ts

@@ -0,0 +1,29 @@
+import { Kysely } from "kysely";
+import type { DatabaseIntrospector, Dialect, DialectAdapter, Driver, QueryCompiler } from "kysely";
+export interface D1Result<T = Record<string, unknown>> {
+    success: boolean;
+    error?: string;
+    results?: T[];
+    meta?: {
+        changes?: number;
+        last_row_id?: number;
+        rows_written?: number;
+    };
+}
+export interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    all<T = Record<string, unknown>>(): Promise<D1Result<T>>;
+    run<T = Record<string, unknown>>(): Promise<D1Result<T>>;
+}
+export interface D1Database {
+    prepare(query: string): D1PreparedStatement;
+}
+export declare class D1Dialect implements Dialect {
+    #private;
+    constructor(database: D1Database);
+    createDriver(): Driver;
+    createQueryCompiler(): QueryCompiler;
+    createAdapter(): DialectAdapter;
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}
+export declare function createD1Db<TDb = unknown>(database: D1Database): Kysely<TDb>;

package/cogsbox-shape-db/dist/cloudflare-d1/d1-driver.js

@@ -0,0 +1,100 @@
+import { CompiledQuery, Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler, } from "kysely";
+export class D1Dialect {
+    #database;
+    constructor(database) {
+        this.#database = database;
+    }
+    createDriver() {
+        return new D1Driver(this.#database);
+    }
+    createQueryCompiler() {
+        return new SqliteQueryCompiler();
+    }
+    createAdapter() {
+        return new SqliteAdapter();
+    }
+    createIntrospector(db) {
+        return new SqliteIntrospector(db);
+    }
+}
+export function createD1Db(database) {
+    return new Kysely({
+        dialect: new D1Dialect(database),
+    });
+}
+class D1Driver {
+    #connection;
+    constructor(database) {
+        this.#connection = new D1Connection(database);
+    }
+    async init(_options) {
+        // Cloudflare D1 bindings are already initialized by the Worker runtime.
+    }
+    async acquireConnection(_options) {
+        return this.#connection;
+    }
+    async beginTransaction(connection, _settings) {
+        await connection.executeQuery(CompiledQuery.raw("begin"));
+    }
+    async commitTransaction(connection) {
+        await connection.executeQuery(CompiledQuery.raw("commit"));
+    }
+    async rollbackTransaction(connection) {
+        await connection.executeQuery(CompiledQuery.raw("rollback"));
+    }
+    async releaseConnection(_connection, _options) {
+        // D1 exposes a stateless binding instead of pooled connections.
+    }
+    async destroy(_options) {
+        // Nothing to close for a Worker binding.
+    }
+}
+class D1Connection {
+    #database;
+    constructor(database) {
+        this.#database = database;
+    }
+    async executeQuery(compiledQuery) {
+        const statement = this.#prepare(compiledQuery);
+        const result = shouldReturnRows(compiledQuery.sql)
+            ? await statement.all()
+            : await statement.run();
+        assertD1Success(result, compiledQuery.sql);
+        return {
+            insertId: result.meta?.last_row_id != null
+                ? BigInt(result.meta.last_row_id)
+                : undefined,
+            numAffectedRows: affectedRows(result),
+            rows: (result.results ?? []),
+        };
+    }
+    async *streamQuery(compiledQuery, _chunkSize) {
+        const result = await this.executeQuery(compiledQuery);
+        for (const row of result.rows) {
+            yield { rows: [row] };
+        }
+    }
+    #prepare(compiledQuery) {
+        const statement = this.#database.prepare(compiledQuery.sql);
+        return compiledQuery.parameters.length > 0
+            ? statement.bind(...compiledQuery.parameters)
+            : statement;
+    }
+}
+function shouldReturnRows(sql) {
+    const trimmed = sql.trim().toLowerCase();
+    return (trimmed.startsWith("select") ||
+        trimmed.startsWith("with") ||
+        trimmed.startsWith("pragma") ||
+        trimmed.startsWith("explain") ||
+        /\breturning\b/i.test(sql));
+}
+function affectedRows(result) {
+    const count = result.meta?.changes ?? result.meta?.rows_written;
+    return count != null ? BigInt(count) : undefined;
+}
+function assertD1Success(result, sql) {
+    if (!result.success) {
+        throw new Error(result.error ?? `D1 query failed: ${sql}`);
+    }
+}

package/cogsbox-shape-db/dist/cloudflare-d1/index.d.ts

@@ -0,0 +1 @@
+export { createD1Db, D1Dialect, type D1Database, type D1PreparedStatement, type D1Result, } from "./d1-driver.js";

package/cogsbox-shape-db/dist/cloudflare-d1/index.js

@@ -0,0 +1 @@
+export { createD1Db, D1Dialect, } from "./d1-driver.js";

package/cogsbox-shape-db/dist/table-db.js

@@ -35,8 +35,9 @@ export class TableDB {
                 }
             }
         }
-        const limit = opts?.limit ?? 100;
-        query = query.limit(limit);
+        if (opts?.limit !== undefined) {
+            query = query.limit(opts.limit);
+        }
         if (opts?.offset !== undefined) {
             query = query.offset(opts.offset);
         }

package/dist/schema.d.ts

@@ -336,6 +336,12 @@ export declare function createSchema<T extends {
     clientSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodClientSchema">>>;
     clientCheckedSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodClientCheckedSchema">>>;
     serverSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodValidationSchema">>>;
+    validators: {
+        sql: z.ZodTypeAny;
+        client: z.ZodTypeAny;
+        clientChecked: z.ZodTypeAny;
+        server: z.ZodTypeAny;
+    };
     defaultValues: Prettify<DeriveDefaults<TActualSchema>>;
     stateType: Prettify<DeriveStateType<TActualSchema>>;
     generateDefaults: () => Prettify<DeriveDefaults<TActualSchema>>;
@@ -400,6 +406,12 @@ type ResolvedRegistryWithSchemas<S extends Record<string, SchemaWithPlaceholders
             clientSchema: z.ZodObject<Prettify<DeriveSchemaByKey<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>, "zodClientSchema">>>;
             clientCheckedSchema: z.ZodObject<Prettify<DeriveSchemaByKey<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>, "zodClientCheckedSchema">>>;
             serverSchema: z.ZodObject<Prettify<DeriveSchemaByKey<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>, "zodValidationSchema">>>;
+            validators: {
+                sql: z.ZodTypeAny;
+                client: z.ZodTypeAny;
+                clientChecked: z.ZodTypeAny;
+                server: z.ZodTypeAny;
+            };
             defaultValues: Prettify<DeriveDefaults<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
             stateType: Prettify<DeriveStateType<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
         };
@@ -511,6 +523,12 @@ export type DeriveViewResult<TTableName extends keyof TRegistry, TSelection, TRe
         clientChecked: z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "clientCheckedSchema">>;
         server: z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "serverSchema">>;
     };
+    validators: {
+        sql: TRegistry[TTableName]["zodSchemas"]["validators"]["sql"];
+        client: TRegistry[TTableName]["zodSchemas"]["validators"]["client"];
+        clientChecked: TRegistry[TTableName]["zodSchemas"]["validators"]["clientChecked"];
+        server: TRegistry[TTableName]["zodSchemas"]["validators"]["server"];
+    };
     transforms: {
         toClient: TRegistry[TTableName]["transforms"]["toClient"];
         toDb: TRegistry[TTableName]["transforms"]["toDb"];
@@ -560,6 +578,12 @@ type RegistryShape = Record<string, {
         clientSchema: z.ZodObject<any>;
         clientCheckedSchema: z.ZodObject<any>;
         serverSchema: z.ZodObject<any>;
+        validators: {
+            sql: z.ZodTypeAny;
+            client: z.ZodTypeAny;
+            clientChecked: z.ZodTypeAny;
+            server: z.ZodTypeAny;
+        };
         defaultValues: any;
         stateType: any;
         deriveDependencies: Record<string, string[]>;
@@ -595,6 +619,12 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
             clientChecked: Resolved[K]["zodSchemas"]["clientCheckedSchema"];
             server: Resolved[K]["zodSchemas"]["serverSchema"];
         };
+        validators: {
+            sql: Resolved[K]["zodSchemas"]["validators"]["sql"];
+            client: Resolved[K]["zodSchemas"]["validators"]["client"];
+            clientChecked: Resolved[K]["zodSchemas"]["validators"]["clientChecked"];
+            server: Resolved[K]["zodSchemas"]["validators"]["server"];
+        };
         transforms: {
             toClient: (dbData: z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>) => z.infer<Resolved[K]["zodSchemas"]["clientSchema"]>;
             toDb: (clientData: z.infer<Resolved[K]["zodSchemas"]["clientSchema"]>) => z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>;

package/dist/schema.js

@@ -787,10 +787,16 @@ export function createSchema(schema, relations) {
         deriveDependencies,
         refineInfo: { groups: refineGroups ?? [], fieldToGroup },
         isClientRecord,
-        sqlSchema: refinedSqlSchema,
-        clientSchema: refinedClientSchema,
-        clientCheckedSchema: refinedClientCheckedSchema,
-        serverSchema: refinedValidationSchema,
+        sqlSchema: finalSqlSchema,
+        clientSchema: finalClientSchema,
+        clientCheckedSchema: finalClientCheckedSchema,
+        serverSchema: finalValidationSchema,
+        validators: {
+            sql: refinedSqlSchema,
+            client: refinedClientSchema,
+            clientChecked: refinedClientCheckedSchema,
+            server: refinedValidationSchema,
+        },
         defaultValues: defaultValues,
         stateType: {},
         generateDefaults,
@@ -1028,6 +1034,12 @@ export function createSchemaBox(schemas, resolutions) {
                 clientChecked: entry.zodSchemas.clientCheckedSchema,
                 server: entry.zodSchemas.serverSchema,
             },
+            validators: {
+                sql: entry.zodSchemas.validators.sql,
+                client: entry.zodSchemas.validators.client,
+                clientChecked: entry.zodSchemas.validators.clientChecked,
+                server: entry.zodSchemas.validators.server,
+            },
             transforms: {
                 toClient: entry.transforms.toClient,
                 toDb: entry.transforms.toDb,
@@ -1172,6 +1184,12 @@ export function createSchemaBox(schemas, resolutions) {
                         clientChecked: view.clientChecked,
                         server: view.server,
                     },
+                    validators: {
+                        sql: view.sql,
+                        client: view.client,
+                        clientChecked: view.clientChecked,
+                        server: view.server,
+                    },
                     transforms: {
                         toClient: viewToClient,
                         toDb: viewToDb,

package/dist/vitest/fullSchema.test.js

@@ -368,7 +368,7 @@ describe("client vs clientChecked schema divergence after .clientCheck()", () =>
             id: 1, password: "abc", confirmPassword: "def",
         });
         expect(clientResult.success).toBe(true);
-        const clientCheckedResult = box.forms.schemas.clientChecked.safeParse({
+        const clientCheckedResult = box.forms.validators.clientChecked.safeParse({
             id: 1, password: "abc", confirmPassword: "def",
         });
         expect(clientCheckedResult.success).toBe(false);
@@ -1204,7 +1204,7 @@ describe("refine", () => {
             }),
         ]);
         const box = createSchemaBox({ forms }, { forms: {} });
-        const result = box.forms.schemas.client.safeParse({
+        const result = box.forms.validators.client.safeParse({
             id: 1,
             password: "secret",
             confirmPassword: "different",
@@ -1213,7 +1213,7 @@ describe("refine", () => {
         if (!result.success) {
             expect(result.error.issues[0].message).toBe("Passwords must match");
         }
-        const validResult = box.forms.schemas.client.safeParse({
+        const validResult = box.forms.validators.client.safeParse({
             id: 1,
             password: "secret",
             confirmPassword: "secret",

package/dist/vitest/refineRuntime.test.js

@@ -32,16 +32,16 @@ describe("refine runtime behavior", () => {
         ]);
         return createSchemaBox({ rules }, { rules: {} });
     }
-    it("schemas.client catches client refine", () => {
+    it("validators.client catches client refine", () => {
         const box = makeRefinedBox();
-        const good = box.rules.schemas.client.safeParse({
+        const good = box.rules.validators.client.safeParse({
             id: 1,
             min: 1,
             max: 10,
             label: "x",
         });
         expect(good.success).toBe(true);
-        const bad = box.rules.schemas.client.safeParse({
+        const bad = box.rules.validators.client.safeParse({
             id: 1,
             min: 10,
             max: 1,
@@ -52,9 +52,9 @@ describe("refine runtime behavior", () => {
             expect(bad.error.issues[0].message).toBe("Max must be > min");
         }
     });
-    it("schemas.clientChecked catches client refine", () => {
+    it("validators.clientChecked catches client refine", () => {
         const box = makeRefinedBox();
-        const bad = box.rules.schemas.clientChecked.safeParse({
+        const bad = box.rules.validators.clientChecked.safeParse({
             id: 1,
             min: 10,
             max: 1,
@@ -65,9 +65,9 @@ describe("refine runtime behavior", () => {
             expect(bad.error.issues[0].message).toBe("Max must be > min");
         }
     });
-    it("schemas.server catches server refine", () => {
+    it("validators.server catches server refine", () => {
         const box = makeRefinedBox();
-        const bad = box.rules.schemas.server.safeParse({
+        const bad = box.rules.validators.server.safeParse({
             id: 1,
             min: 1,
             max: 10,
@@ -78,9 +78,9 @@ describe("refine runtime behavior", () => {
             expect(bad.error.issues[0].message).toBe("Label required");
         }
     });
-    it("schemas.sql catches server refine", () => {
+    it("validators.sql catches server refine", () => {
         const box = makeRefinedBox();
-        const bad = box.rules.schemas.sql.safeParse({
+        const bad = box.rules.validators.sql.safeParse({
             id: 1,
             min: 1,
             max: 10,
@@ -122,36 +122,18 @@ describe("refine runtime behavior", () => {
         });
         expect(good.success).toBe(true);
     });
-    it("view keeps leaf refines and prefixes issue paths", () => {
-        const rules = schema({
-            _tableName: "rules",
-            id: s.sqlite({ type: "int", pk: true }),
-            min: s
-                .sqlite({ type: "int", field: "minField" })
-                .client({ value: 0 }),
-            max: s.sqlite({ type: "int" }).client({ value: 0 }),
-        }).refine((r) => [
-            r("clientCheck", (row) => row.min >= row.max
-                ? { path: ["max"], message: "Max must be > min" }
-                : undefined, ["min", "max"]),
-        ]);
-        const journal = schema({
-            _tableName: "journal",
-            id: s.sqlite({ type: "int", pk: true }),
-            rules: s.hasOne(true),
-        });
-        const box = createSchemaBox({ rules, journal }, {
-            journal: { rules: { fromKey: "id", toKey: rules.id } },
-        });
-        const view = box.journal.createView({ rules: true });
-        const bad = view.schemas.clientChecked.safeParse({
+    it("validators enforce refine on direct table schemas", () => {
+        const box = makeRefinedBox();
+        const bad = box.rules.validators.clientChecked.safeParse({
             id: 1,
-            rules: { id: 1, min: 10, max: 1 },
+            min: 10,
+            max: 1,
+            label: "x",
         });
         expect(bad.success).toBe(false);
         if (!bad.success) {
             expect(bad.error.issues[0]).toMatchObject({
-                path: ["rules", "max"],
+                path: ["max"],
                 message: "Max must be > min",
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-shape",
-  "version": "0.5.206",
+  "version": "0.5.208",
   "description": "A TypeScript library for creating type-safe database schemas with Zod validation, SQL type definitions, and automatic client/server transformations. Unifies client, server, and database types through a single schema definition, with built-in support for relationships and serialization.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,6 +37,11 @@
       "import": "./cogsbox-shape-db/dist/sqlite/index.js",
       "default": "./cogsbox-shape-db/dist/sqlite/index.js"
     },
+    "./db/cloudflare-d1": {
+      "types": "./cogsbox-shape-db/dist/cloudflare-d1/index.d.ts",
+      "import": "./cogsbox-shape-db/dist/cloudflare-d1/index.js",
+      "default": "./cogsbox-shape-db/dist/cloudflare-d1/index.js"
+    },
     "./state": {
       "types": "./cogsbox-shape-state/dist/index.d.ts",
       "import": "./cogsbox-shape-state/dist/index.js",