cogsbox-shape 0.5.190 → 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

@@ -194,11 +194,38 @@ type PickPrimaryKeys<T extends ShapeSchema> = {
         };
     } ? K : never]: T[K];
 };
+type PickClientOnlyKeys<T extends ShapeSchema> = {
+    [K in keyof T]: T[K] extends {
+        config: {
+            sql: null;
+        };
+    } ? K : never;
+}[keyof T];
+type PickDbFieldKeys<T extends ShapeSchema> = {
+    [K in keyof T]: T[K] extends {
+        config: {
+            sql: infer TSql;
+        };
+    } ? 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>> & {
     __primaryKeySQL?: string;
-    __derives?: Record<string, (row: any) => any>;
+    __derives?: {
+        forClient?: Record<string, (row: any) => any>;
+        forDb?: Record<string, (row: any) => any>;
+    };
     primaryKeySQL: (definer: (pkFields: PickPrimaryKeys<T>) => string) => SchemaBuilder<T>;
-    derive: <D extends Partial<Record<keyof T, (row: Prettify<z.infer<z.ZodObject<Prettify<DeriveSchemaByKey<T, "zodClientSchema">>>>>) => any>>>(derivers: D) => SchemaBuilder<T>;
+    derive: (derivers: {
+        forClient?: {
+            [K in PickClientOnlyKeys<T>]?: (row: InferClientRow<T>) => any;
+        };
+        forDb?: {
+            [K in PickDbFieldKeys<T>]?: (row: InferClientRow<T>) => any;
+        };
+    }) => SchemaBuilder<T>;
 };
 export declare function schema<T extends string, U extends ShapeSchema<T>>(schema: U): SchemaBuilder<U>;
 export type RelationType = "hasMany" | "hasOne" | "manyToMany";

package/dist/schema.js

@@ -578,6 +578,7 @@ export function createSchema(schema, relations) {
     const generateDefaults = () => {
         const freshDefaults = {};
         for (const key in defaultGenerators) {
+            // ... same logic for mapping standard defaults ...
             const generatorOrValue = defaultGenerators[key];
             let rawValue = isFunction(generatorOrValue)
                 ? generatorOrValue({ uuid })
@@ -586,9 +587,10 @@ export function createSchema(schema, relations) {
                 ? fieldTransforms[key].toClient(rawValue)
                 : rawValue;
         }
-        if (derives) {
-            for (const key in derives) {
-                freshDefaults[key] = derives[key](freshDefaults);
+        // Only apply client derivations
+        if (derives?.forClient) {
+            for (const key in derives.forClient) {
+                freshDefaults[key] = derives.forClient[key]?.(freshDefaults);
             }
         }
         return freshDefaults;
@@ -606,31 +608,36 @@ export function createSchema(schema, relations) {
                 ? transform(dbObject[dbKey])
                 : dbObject[dbKey];
         }
-        if (derives) {
-            for (const key in derives) {
-                clientObject[key] = derives[key](clientObject);
+        // Only apply Client derives AFTER mapping standard fields
+        if (derives?.forClient) {
+            for (const key in derives.forClient) {
+                clientObject[key] = derives.forClient[key]?.(clientObject);
             }
         }
         return clientObject;
     };
     const toDb = (clientObject) => {
-        // 1. Calculate derives FIRST based on the client data
-        const clientWithDerives = { ...clientObject };
-        if (derives) {
-            for (const key in derives) {
-                clientWithDerives[key] = derives[key](clientWithDerives);
-            }
-        }
-        // 2. Map the data (including the newly derived fields) to the DB object
         const dbObject = {};
-        for (const clientKey in clientWithDerives) {
-            if (clientWithDerives[clientKey] === undefined)
+        // 1. Map standard client fields to DB fields
+        for (const clientKey in clientObject) {
+            if (clientObject[clientKey] === undefined)
+                continue;
+            const dbKey = clientToDbKeys[clientKey];
+            if (!dbKey)
                 continue;
-            const dbKey = clientToDbKeys[clientKey] || clientKey;
             const transform = fieldTransforms[clientKey]?.toDb;
             dbObject[dbKey] = transform
-                ? transform(clientWithDerives[clientKey])
-                : clientWithDerives[clientKey];
+                ? transform(clientObject[clientKey])
+                : clientObject[clientKey];
+        }
+        // 2. Map Database ONLY derives directly to the dbObject
+        if (derives?.forDb) {
+            for (const schemaKey in derives.forDb) {
+                // Resolve custom DB column name if they used s.sql({ field: "custom_name" })
+                const sqlConfig = fullSchema[schemaKey]?.config?.sql;
+                const dbKey = sqlConfig?.field || schemaKey;
+                dbObject[dbKey] = derives.forDb[schemaKey]?.(clientObject);
+            }
         }
         return dbObject;
     };
@@ -639,9 +646,11 @@ export function createSchema(schema, relations) {
     const finalClientSchema = z.object(clientFields);
     const finalValidationSchema = z.object(serverFields);
     const deriveDependencies = {};
-    if (derives) {
+    const trackDeriveDependencies = (deriveGroup) => {
+        if (!deriveGroup)
+            return;
         const trackingSeed = { ...defaultValues };
-        for (const key in derives) {
+        for (const key in deriveGroup) {
             const accessed = new Set();
             const trackingRow = new Proxy(trackingSeed, {
                 get(target, prop, receiver) {
@@ -652,12 +661,14 @@ export function createSchema(schema, relations) {
                 },
             });
             try {
-                derives[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,
@@ -701,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;
             }
         }
@@ -945,9 +952,10 @@ export function createSchemaBox(schemas, resolutions) {
                             }
                         }
                     }
-                    if (regEntry.rawSchema.__derives) {
-                        for (const key in regEntry.rawSchema.__derives) {
-                            baseMapped[key] = regEntry.rawSchema.__derives[key](baseMapped);
+                    if (regEntry.rawSchema.__derives?.forClient) {
+                        for (const key in regEntry.rawSchema.__derives.forClient) {
+                            baseMapped[key] =
+                                regEntry.rawSchema.__derives.forClient[key](baseMapped);
                         }
                     }
                     return baseMapped;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogsbox-shape",
-  "version": "0.5.190",
+  "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",