cogsbox-shape 0.5.191 → 0.5.192

package/README.md

@@ -178,9 +178,12 @@ const products = schema({
 });
 ```
 
-#### Derived Fields (`.derive()`)
-
-`.derive()` populates _existing fields_ dynamically on read and default generation. Because you define the fields first, derived fields can be either standard DB fields or Client-only fields.
+#### Derived Fields (`.derive()`)
+
+`.derive()` populates _existing fields_ dynamically. Define the target field first, then choose where the derivation runs:
+
+- `forClient` computes client-only fields during `generateDefaults()` and `toClient()`.
+- `forDb` computes DB-backed fields during `toDb()`, `parseForDb()`, and ORM writes. Use `sqlOnly: true` when the computed column should stay hidden from the client.
 
 ```typescript
 const users = schema({
@@ -188,16 +191,22 @@ const users = schema({
   firstName: s.sql({ type: "varchar" }).clientInput({ value: "John" }),
   lastName: s.sql({ type: "varchar" }).clientInput({ value: "Doe" }),
 
-  // 1. Defined purely as a client field
-  fullName: s.clientInput(""),
-  // 2. Defined as a DB field
-  searchIndex: s.sql({ type: "varchar" }),
-}).derive({
-  // Computes on toClient() and generateDefaults()
-  fullName: (row) => `${row.firstName} ${row.lastName}`,
-  searchIndex: (row) => `${row.firstName} ${row.lastName}`.toLowerCase(),
-});
-```
+  // Virtual field. It exists in app/view state, not SQL.
+  fullName: s.clientInput(""),
+
+  // Hidden DB column. It is written to SQL, but not sent to the client.
+  searchIndex: s.sql({ type: "varchar", sqlOnly: true }),
+}).derive({
+  forClient: {
+    fullName: (row) => `${row.firstName} ${row.lastName}`,
+  },
+  forDb: {
+    searchIndex: (row) => `${row.firstName} ${row.lastName}`.toLowerCase(),
+  },
+});
+```
+
+During partial ORM updates, DB-backed derivations fetch only missing dependency fields they actually read, then recompute the affected `forDb` fields. Client-only derived fields are ignored by SQL writes.
 
 ### Schema Object Structure
 
@@ -337,12 +346,31 @@ type UserWithPosts = z.infer<typeof userWithPosts.schemas.client>;
 //   posts: { id: number; title: string; authorId: number; }[]
 // }
 
-// Views also have transforms for the selected fields
-const { defaults, transforms } = userWithPosts;
-// transforms.toClient() handles nested relation transforms automatically
-```
-
-### 5. Nested Defaults and Form Definitions (`defaultsDefinition`)
+// Views also have transforms for the selected fields
+const { defaults, transforms } = userWithPosts;
+// transforms.toClient() handles nested relation transforms automatically
+```
+
+When a box is connected to the ORM, view reads hydrate the selected relation tree before parsing:
+
+```typescript
+import { connect } from "cogsbox-shape/db";
+import { createSqliteDb } from "cogsbox-shape/db/sqlite";
+
+const db = createSqliteDb("app.sqlite");
+const bx = connect(box, db);
+
+const userView = bx.users.createView({
+  posts: true,
+});
+
+const user = await userView.db.findById(1);
+// user.posts is loaded and validated as part of the view shape
+```
+
+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`)
 
 When working with forms and nested array relations (like `hasMany`), you often need the default state for a _single new item_ to add to a form array.
 

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

@@ -80,6 +80,7 @@ export class TableDB {
         const dbData = this.transforms.parseForDb(data);
         const parsedDbOnlyData = this.parseDbOnlyData(dbOnlyData, {
             requireRequired: true,
+            presentDbData: dbData,
         });
         const clientPkClientKeys = this.meta.clientPkFields;
         const pkDbNames = new Set(clientPkClientKeys.map((k) => {
@@ -225,7 +226,11 @@ export class TableDB {
     parseDbOnlyData(dbOnlyData, opts = { requireRequired: false }) {
         if (opts.requireRequired) {
             for (const requiredKey of this.meta.sqlOnlyRequiredClientFields) {
-                if (!dbOnlyData || dbOnlyData[requiredKey] === undefined) {
+                const field = this.meta.dbFields.get(requiredKey);
+                const dbName = field?.dbName ?? requiredKey;
+                const alreadyPresent = opts.presentDbData?.[dbName] !== undefined;
+                if (!alreadyPresent &&
+                    (!dbOnlyData || dbOnlyData[requiredKey] === undefined)) {
                     throw new Error(`Missing required sqlOnly field "${requiredKey}" for "${this.meta.tableName}".`);
                 }
             }

package/dist/schema.d.ts

@@ -201,14 +201,14 @@ type PickClientOnlyKeys<T extends ShapeSchema> = {
         };
     } ? K : never;
 }[keyof T];
-type PickSqlOnlyKeys<T extends ShapeSchema> = {
+type PickDbFieldKeys<T extends ShapeSchema> = {
     [K in keyof T]: T[K] extends {
         config: {
-            sql: {
-                sqlOnly: true;
-            };
+            sql: infer TSql;
         };
-    } ? K : never;
+    } ? TSql extends null ? never : TSql extends {
+        type: "hasMany" | "hasOne" | "belongsTo" | "manyToMany";
+    } ? never : K : never;
 }[keyof T];
 type InferClientRow<T extends ShapeSchema> = Prettify<z.infer<z.ZodObject<Prettify<DeriveSchemaByKey<T, "zodClientSchema">>>>>;
 type SchemaBuilder<T extends ShapeSchema> = Prettify<EnrichFields<T>> & {
@@ -223,7 +223,7 @@ type SchemaBuilder<T extends ShapeSchema> = Prettify<EnrichFields<T>> & {
             [K in PickClientOnlyKeys<T>]?: (row: InferClientRow<T>) => any;
         };
         forDb?: {
-            [K in PickSqlOnlyKeys<T>]?: (row: InferClientRow<T>) => any;
+            [K in PickDbFieldKeys<T>]?: (row: InferClientRow<T>) => any;
         };
     }) => SchemaBuilder<T>;
 };

package/dist/schema.js

@@ -622,7 +622,9 @@ export function createSchema(schema, relations) {
         for (const clientKey in clientObject) {
             if (clientObject[clientKey] === undefined)
                 continue;
-            const dbKey = clientToDbKeys[clientKey] || clientKey;
+            const dbKey = clientToDbKeys[clientKey];
+            if (!dbKey)
+                continue;
             const transform = fieldTransforms[clientKey]?.toDb;
             dbObject[dbKey] = transform
                 ? transform(clientObject[clientKey])
@@ -644,9 +646,11 @@ export function createSchema(schema, relations) {
     const finalClientSchema = z.object(clientFields);
     const finalValidationSchema = z.object(serverFields);
     const deriveDependencies = {};
-    if (derives?.forClient) {
+    const trackDeriveDependencies = (deriveGroup) => {
+        if (!deriveGroup)
+            return;
         const trackingSeed = { ...defaultValues };
-        for (const key in derives.forClient) {
+        for (const key in deriveGroup) {
             const accessed = new Set();
             const trackingRow = new Proxy(trackingSeed, {
                 get(target, prop, receiver) {
@@ -657,12 +661,14 @@ export function createSchema(schema, relations) {
                 },
             });
             try {
-                derives.forClient[key]?.(trackingRow);
+                deriveGroup[key]?.(trackingRow);
             }
             catch (e) { }
-            deriveDependencies[key] = Array.from(accessed);
+            deriveDependencies[key] = Array.from(new Set([...(deriveDependencies[key] ?? []), ...accessed]));
         }
-    }
+    };
+    trackDeriveDependencies(derives?.forClient);
+    trackDeriveDependencies(derives?.forDb);
     return {
         pk: pkKeys.length ? pkKeys : null,
         clientPk: clientPkKeys.length ? clientPkKeys : null,
@@ -706,10 +712,6 @@ function createViewObject(initialRegistryKey, selection, registry, tableNameToRe
                 registryEntry.zodSchemas.clientPk.length > 0);
             checkedTables[currentRegistryKey] = hasPks;
             if (!hasPks) {
-                console.log(`Table ${currentRegistryKey} missing pk/clientPk:`, {
-                    pk: registryEntry.zodSchemas?.pk,
-                    clientPk: registryEntry.zodSchemas?.clientPk,
-                });
                 allTablesSupportsReconciliation = false;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-shape",
-  "version": "0.5.191",
+  "version": "0.5.192",
   "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",
@@ -22,16 +22,20 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./db": {
       "types": "./cogsbox-shape-db/dist/index.d.ts",
-      "import": "./cogsbox-shape-db/dist/index.js"
+      "import": "./cogsbox-shape-db/dist/index.js",
+      "default": "./cogsbox-shape-db/dist/index.js"
     },
     "./db/sqlite": {
       "types": "./cogsbox-shape-db/dist/sqlite/index.d.ts",
-      "import": "./cogsbox-shape-db/dist/sqlite/index.js"
-    }
+      "import": "./cogsbox-shape-db/dist/sqlite/index.js",
+      "default": "./cogsbox-shape-db/dist/sqlite/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "keywords": [
     "typescript",