cogsbox-shape 0.5.195 → 0.5.196

package/README.md

@@ -248,8 +248,8 @@ const events = schema({
     schema: z.string().nullable(),
   }),
   isPublished: s.sqlite({ type: "boolean" }).clientInput({ value: false }),
-}).refine({
-  server: (row) => {
+}).refine((r) => [
+  r("server", (row) => {
     const errors: { path: string[]; message: string }[] = [];
     if (row.startDate && row.endDate && row.startDate > row.endDate) {
       errors.push({ path: ["endDate"], message: "End date must be after start date" });
@@ -258,8 +258,8 @@ const events = schema({
       errors.push({ path: ["content"], message: "Published events must have content" });
     }
     return errors.length > 0 ? errors : undefined;
-  },
-});
+  }),
+]);
 
 const box = createSchemaBox({ events }, { events: {} });
 
@@ -271,26 +271,36 @@ box.events.transforms.parseForDb({
 // Throws: "End date must be after start date"
 ```
 
-The `refine()` config accepts two optional callbacks:
+The `refine()` method takes a callback that receives an `r` helper function. Each call to `r(layer, check, deps?)` creates a refine entry:
 
-| Callback | Runs on | Purpose |
-|----------|---------|---------|
-| `server` | `parseForDb()` | Cross-field validation before DB writes |
-| `client` | `clientInput` schema | Cross-field validation on client input |
+| Layer | Applies to | Purpose |
+|-------|-----------|---------|
+| `"server"` | `parseForDb()`, `server` schema | Cross-field validation before DB writes |
+| `"client"` | `client` schema | Cross-field validation on client output |
+| `"clientInput"` | `clientInput` schema | Cross-field validation on raw client input |
+| `"sql"` | `parseFromDb()`, `sql` schema | Cross-field validation on DB reads |
+| `"all"` | all of the above | Universal cross-field validation |
+| `string[]` | specified layers | Apply to multiple layers at once |
 
-Each callback receives the full row and returns:
+The check function receives the full row and returns:
 - `undefined` or `null` — validation passes
 - A single `{ path: string[]; message: string }` — one error
 - An array of `{ path: string[]; message: string }` — multiple errors
 
-**Dependency tracking**: Same proxy-based approach as `derive()` — the library tracks which fields the refine function reads. This is used by the ORM to know which fields to include during partial updates. The same caveat applies: conditional branches with falsy defaults can hide dependencies.
+Optional third argument `deps` specifies explicit dependency fields as a string or string array. If omitted, the library uses proxy-based tracking (same caveat as `derive()` — conditional branches with falsy defaults can hide dependencies).
+
+**Dependency tracking**: Dependencies are exposed as `refineInfo` on the box entry:
+```typescript
+box.events.refineInfo;
+// { groups: RefineEntry[], fieldToGroup: Record<string, number[]> }
+```
 
 **Chaining**: `refine()` can be chained after `derive()`:
 
 ```typescript
 schema({ ... })
   .derive({ forDb: { fullName: (row) => `${row.firstName} ${row.lastName}` } })
-  .refine({ server: (row) => { ... } });
+  .refine((r) => [r("server", (row) => { ... })]);
 ```
 
 **Note**: `parsePatchForDb` uses the base schema (without refinement) since partial data may not satisfy cross-field rules.
@@ -310,7 +320,7 @@ 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.refineDependencies; // Refinement dependencies ({ server: string[], client: string[] })
+schema.refineInfo; // Refinement info ({ groups: RefineEntry[], fieldToGroup: Record<string, number[]> })
 ```
 
 ## Using Schemas

package/cogsbox-shape-db/dist/connect.d.ts

@@ -6,7 +6,7 @@ type Row<T> = T extends readonly (infer TItem)[] ? TItem : T;
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-type SchemaMetaKey = "_tableName" | "__primaryKeySQL" | "__derives" | "__refinements" | "primaryKeySQL" | "derive" | "refine";
+type SchemaMetaKey = "_tableName" | "__primaryKeySQL" | "__derives" | "__refines" | "primaryKeySQL" | "derive" | "refine";
 type SqlConfigOf<TField> = TField extends {
     config: {
         sql: infer TSql;

package/dist/schema.d.ts

@@ -209,7 +209,16 @@ export type RefinementError = {
     path: string[];
     message: string;
 };
-export type RefinementFn<T> = (row: T) => RefinementError | RefinementError[] | undefined | null;
+type RefineLayer = "client" | "server" | "sql" | "clientInput" | "all";
+type RefineEntry = {
+    layers: RefineLayer[];
+    deps: string[] | null;
+    check: (row: any) => RefinementError | RefinementError[] | undefined | null;
+};
+type RefineHelper = {
+    (layers: RefineLayer | RefineLayer[], check: (row: any) => RefinementError | RefinementError[] | undefined | null): RefineEntry;
+    (layers: RefineLayer | RefineLayer[], check: (row: any) => RefinementError | RefinementError[] | undefined | null, deps: string | string[]): RefineEntry;
+};
 type PickPrimaryKeys<T extends ShapeSchema> = {
     [K in keyof T as T[K] extends {
         config: {
@@ -242,10 +251,7 @@ type SchemaBuilder<T extends ShapeSchema> = Prettify<EnrichFields<T>> & {
         forClient?: Record<string, (row: any) => any>;
         forDb?: Record<string, (row: any) => any>;
     };
-    __refinements?: {
-        server?: RefinementFn<InferClientRow<T>>;
-        client?: RefinementFn<z.infer<z.ZodObject<Prettify<DeriveSchemaByKey<EnrichFields<T>, "zodClientInputSchema">>>>>;
-    };
+    __refines?: RefineEntry[];
     primaryKeySQL: (definer: (pkFields: PickPrimaryKeys<T>) => string) => SchemaBuilder<T>;
     derive: (derivers: {
         forClient?: {
@@ -255,10 +261,7 @@ type SchemaBuilder<T extends ShapeSchema> = Prettify<EnrichFields<T>> & {
             [K in PickDbFieldKeys<T>]?: (row: InferClientRow<T>) => any;
         };
     }) => SchemaBuilder<T>;
-    refine: (refinements: {
-        server?: RefinementFn<InferClientRow<T>>;
-        client?: RefinementFn<z.infer<z.ZodObject<Prettify<DeriveSchemaByKey<EnrichFields<T>, "zodClientInputSchema">>>>>;
-    }) => SchemaBuilder<T>;
+    refine: (fn: (r: RefineHelper) => RefineEntry[]) => SchemaBuilder<T>;
 };
 export declare function schema<T extends string, U extends ShapeSchema<T>>(schema: U): SchemaBuilder<U>;
 export type RelationType = "hasMany" | "hasOne" | "manyToMany";
@@ -298,9 +301,9 @@ export declare function createSchema<T extends {
     pk: string[] | null;
     clientPk: string[] | null;
     deriveDependencies: Record<string, string[]>;
-    refineDependencies: {
-        server: string[];
-        client: string[];
+    refineInfo: {
+        groups: RefineEntry[];
+        fieldToGroup: Record<string, number[]>;
     };
     isClientRecord: (record: any) => boolean;
     sqlSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodSqlSchema">>>;
@@ -383,9 +386,9 @@ type ResolvedRegistryWithSchemas<S extends Record<string, SchemaWithPlaceholders
         };
         pk: string[] | null;
         clientPk: string[] | null;
-        refineDependencies: {
-            server: string[];
-            client: string[];
+        refineInfo: {
+            groups: RefineEntry[];
+            fieldToGroup: Record<string, number[]>;
         };
         isClientRecord: (record: any) => boolean;
         generateDefaults: () => Prettify<DeriveDefaults<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
@@ -533,9 +536,9 @@ type RegistryShape = Record<string, {
         defaultValues: any;
         stateType: any;
         deriveDependencies: Record<string, string[]>;
-        refineDependencies: {
-            server: string[];
-            client: string[];
+        refineInfo: {
+            groups: RefineEntry[];
+            fieldToGroup: Record<string, number[]>;
         };
     };
     transforms: {
@@ -548,9 +551,9 @@ type RegistryShape = Record<string, {
     pk: string[] | null;
     clientPk: string[] | null;
     deriveDependencies: Record<string, string[]>;
-    refineDependencies: {
-        server: string[];
-        client: string[];
+    refineInfo: {
+        groups: RefineEntry[];
+        fieldToGroup: Record<string, number[]>;
     };
     isClientRecord: (record: any) => boolean;
     generateDefaults: () => any;
@@ -579,9 +582,9 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
         pk: string[] | null;
         clientPk: string[] | null;
         deriveDependencies: Record<string, string[]>;
-        refineDependencies: {
-            server: string[];
-            client: string[];
+        refineInfo: {
+            groups: RefineEntry[];
+            fieldToGroup: Record<string, number[]>;
         };
         isClientRecord: (record: any) => boolean;
         nav: NavigationProxy<K & string, Resolved>;
@@ -608,7 +611,7 @@ type GetDbKey<K, Field> = Field extends Reference<infer TGetter> ? ReturnType<TG
     };
 } ? string extends F ? K : F : K;
 type DeriveSchemaByKey<T, Key extends "zodSqlSchema" | "zodClientInputSchema" | "zodClientSchema" | "zodValidationSchema", Depth extends any[] = []> = Depth["length"] extends 10 ? any : {
-    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refines" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;
@@ -635,7 +638,7 @@ type DeriveSchemaByKey<T, Key extends "zodSqlSchema" | "zodClientInputSchema" |
     } ? ZodSchema : never;
 };
 type DeriveDefaults<T, Depth extends any[] = []> = Prettify<Depth["length"] extends 10 ? any : {
-    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refines" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;
@@ -658,7 +661,7 @@ type DeriveDefaults<T, Depth extends any[] = []> = Prettify<Depth["length"] exte
     } ? z.infer<TClient> : never;
 }>;
 type DeriveStateType<T, Depth extends any[] = []> = Prettify<Depth["length"] extends 10 ? any : {
-    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refines" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;

package/dist/schema.js

@@ -357,7 +357,7 @@ export function schema(schema) {
     enrichedSchema[SchemaWrapperBrand] = true;
     enrichedSchema.__primaryKeySQL = undefined;
     enrichedSchema.__derives = undefined;
-    enrichedSchema.__refinements = undefined;
+    enrichedSchema.__refines = undefined;
     enrichedSchema.primaryKeySQL = function (definer) {
         const pkFieldsOnly = {};
         for (const key in schema) {
@@ -375,8 +375,16 @@ export function schema(schema) {
         enrichedSchema.__derives = derivers;
         return enrichedSchema;
     };
-    enrichedSchema.refine = function (refinements) {
-        enrichedSchema.__refinements = refinements;
+    enrichedSchema.refine = function (fn) {
+        const r = (layers, check, deps) => {
+            const layerArr = Array.isArray(layers) ? layers : [layers];
+            return {
+                layers: layerArr,
+                deps: deps ? (Array.isArray(deps) ? deps : [deps]) : null,
+                check,
+            };
+        };
+        enrichedSchema.__refines = fn(r);
         return enrichedSchema;
     };
     return enrichedSchema;
@@ -445,7 +453,7 @@ export function createSchema(schema, relations) {
     let pkKeys = [];
     let clientPkKeys = [];
     const derives = schema.__derives;
-    const refinements = schema.__refinements;
+    const refineGroups = schema.__refines;
     for (const key in fullSchema) {
         const value = fullSchema[key];
         if (key === "_tableName" ||
@@ -684,86 +692,76 @@ export function createSchema(schema, relations) {
     };
     trackDeriveDependencies(derives?.forClient);
     trackDeriveDependencies(derives?.forDb);
-    const refineDependencies = { server: [], client: [] };
-    const trackRefinementDependencies = (fn, key) => {
-        if (!fn)
-            return;
-        const accessed = new Set();
-        const trackingRow = new Proxy(defaultValues, {
-            get(target, prop, receiver) {
-                if (typeof prop === "string") {
-                    accessed.add(prop);
-                }
-                return Reflect.get(target, prop, receiver);
-            },
-        });
-        try {
-            fn(trackingRow);
-        }
-        catch (e) { }
-        refineDependencies[key] = Array.from(accessed);
-    };
-    trackRefinementDependencies(refinements?.server, "server");
-    trackRefinementDependencies(refinements?.client, "client");
-    let refinedValidationSchema = finalValidationSchema;
-    if (refinements?.server) {
-        const serverRefine = refinements.server;
-        refinedValidationSchema = finalValidationSchema.superRefine((data, ctx) => {
-            const result = serverRefine(data);
-            if (!result)
-                return;
-            const errors = Array.isArray(result) ? result : [result];
-            for (const err of errors) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: err.message,
-                    path: err.path,
-                });
-            }
-        });
-    }
+    let refinedSqlSchema = finalSqlSchema;
     let refinedClientInputSchema = finalClientInputSchema;
     let refinedClientSchema = finalClientSchema;
-    if (refinements?.client) {
-        const clientRefine = refinements.client;
-        const refineFn = (data, ctx) => {
-            const result = clientRefine(data);
-            if (!result)
-                return;
-            const errors = Array.isArray(result) ? result : [result];
-            for (const err of errors) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: err.message,
-                    path: err.path,
+    let refinedValidationSchema = finalValidationSchema;
+    const fieldToGroup = {};
+    if (refineGroups) {
+        for (let i = 0; i < refineGroups.length; i++) {
+            const entry = refineGroups[i];
+            let { layers, deps, check } = entry;
+            const applyTo = layers.includes("all")
+                ? ["sql", "clientInput", "client", "server"]
+                : layers;
+            // Track deps from proxy if not provided explicitly
+            if (!deps) {
+                const accessed = new Set();
+                const trackingRow = new Proxy(defaultValues, {
+                    get(target, prop, receiver) {
+                        if (typeof prop === "string")
+                            accessed.add(prop);
+                        return Reflect.get(target, prop, receiver);
+                    },
                 });
+                try {
+                    check(trackingRow);
+                }
+                catch (e) { }
+                deps = Array.from(accessed);
+                entry.deps = deps;
             }
-        };
-        refinedClientInputSchema = finalClientInputSchema.superRefine(refineFn);
-        refinedClientSchema = finalClientSchema.superRefine(refineFn);
-    }
-    let refinedSqlSchema = finalSqlSchema;
-    if (refinements?.server) {
-        const serverRefine = refinements.server;
-        refinedSqlSchema = finalSqlSchema.superRefine((data, ctx) => {
-            const result = serverRefine(data);
-            if (!result)
-                return;
-            const errors = Array.isArray(result) ? result : [result];
-            for (const err of errors) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: err.message,
-                    path: err.path,
-                });
+            for (const dep of deps) {
+                if (!fieldToGroup[dep])
+                    fieldToGroup[dep] = [];
+                fieldToGroup[dep].push(i);
             }
-        });
+            const refineFn = (data, ctx) => {
+                const result = check(data);
+                if (!result)
+                    return;
+                const errors = Array.isArray(result) ? result : [result];
+                for (const err of errors) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: err.message,
+                        path: err.path,
+                    });
+                }
+            };
+            for (const layer of applyTo) {
+                switch (layer) {
+                    case "sql":
+                        refinedSqlSchema = refinedSqlSchema.superRefine(refineFn);
+                        break;
+                    case "clientInput":
+                        refinedClientInputSchema = refinedClientInputSchema.superRefine(refineFn);
+                        break;
+                    case "client":
+                        refinedClientSchema = refinedClientSchema.superRefine(refineFn);
+                        break;
+                    case "server":
+                        refinedValidationSchema = refinedValidationSchema.superRefine(refineFn);
+                        break;
+                }
+            }
+        }
     }
     return {
         pk: pkKeys.length ? pkKeys : null,
         clientPk: clientPkKeys.length ? clientPkKeys : null,
         deriveDependencies,
-        refineDependencies,
+        refineInfo: { groups: refineGroups ?? [], fieldToGroup },
         isClientRecord,
         sqlSchema: refinedSqlSchema,
         clientInputSchema: refinedClientInputSchema,
@@ -931,7 +929,7 @@ export function createSchemaBox(schemas, resolutions) {
             pk: zodSchemas.pk,
             clientPk: zodSchemas.clientPk,
             deriveDependencies: zodSchemas.deriveDependencies,
-            refineDependencies: zodSchemas.refineDependencies,
+            refineInfo: zodSchemas.refineInfo,
             isClientRecord: zodSchemas.isClientRecord,
             generateDefaults: zodSchemas.generateDefaults,
         };
@@ -1017,7 +1015,7 @@ export function createSchemaBox(schemas, resolutions) {
             pk: entry.pk,
             clientPk: entry.clientPk,
             deriveDependencies: entry.deriveDependencies,
-            refineDependencies: entry.refineDependencies,
+            refineInfo: entry.refineInfo,
             isClientRecord: entry.isClientRecord,
             nav: createNavProxy(tableName, finalRegistry),
             createView: (selection) => {

package/dist/vitest/fullSchema.test.js

@@ -1017,8 +1017,8 @@ describe("refine", () => {
                 schema: z.string().nullable(),
             }),
             isPublished: s.sqlite({ type: "boolean" }).clientInput({ value: false }),
-        }).refine({
-            server: (row) => {
+        }).refine((r) => [
+            r("server", (row) => {
                 const errors = [];
                 if (row.startDate && row.endDate && row.startDate > row.endDate) {
                     errors.push({
@@ -1033,8 +1033,8 @@ describe("refine", () => {
                     });
                 }
                 return errors.length > 0 ? errors : undefined;
-            },
-        });
+            }),
+        ]);
         const box = createSchemaBox({ events }, { events: {} });
         expect(() => box.events.transforms.parseForDb({
             id: 1,
@@ -1070,8 +1070,8 @@ describe("refine", () => {
             id: s.sqlite({ type: "int", pk: true }),
             password: s.sqlite({ type: "varchar" }).clientInput({ value: "" }),
             confirmPassword: s.sqlite({ type: "varchar" }).clientInput({ value: "" }),
-        }).refine({
-            client: (row) => {
+        }).refine((r) => [
+            r("clientInput", (row) => {
                 if (row.password !== row.confirmPassword) {
                     return {
                         path: ["confirmPassword"],
@@ -1079,8 +1079,8 @@ describe("refine", () => {
                     };
                 }
                 return undefined;
-            },
-        });
+            }),
+        ]);
         const box = createSchemaBox({ forms }, { forms: {} });
         const result = box.forms.schemas.clientInput.safeParse({
             id: 1,
@@ -1098,23 +1098,25 @@ describe("refine", () => {
         });
         expect(validResult.success).toBe(true);
     });
-    it("should track refinement dependencies", () => {
+    it("should track refinement dependencies via fieldToGroup", () => {
         const items = schema({
             _tableName: "items",
             id: s.sqlite({ type: "int", pk: true }),
             min: s.sqlite({ type: "int" }).clientInput({ value: 0 }),
             max: s.sqlite({ type: "int" }).clientInput({ value: 100 }),
-        }).refine({
-            server: (row) => {
+        }).refine((r) => [
+            r("server", (row) => {
                 if (row.min > row.max) {
                     return { path: ["max"], message: "Max must be >= min" };
                 }
                 return undefined;
-            },
-        });
+            }),
+        ]);
         const box = createSchemaBox({ items }, { items: {} });
-        expect(box.items.refineDependencies.server).toEqual(["min", "max"]);
-        expect(box.items.refineDependencies.client).toEqual([]);
+        expect(box.items.refineInfo.fieldToGroup).toHaveProperty("min");
+        expect(box.items.refineInfo.fieldToGroup).toHaveProperty("max");
+        expect(box.items.refineInfo.groups[0].deps).toContain("min");
+        expect(box.items.refineInfo.groups[0].deps).toContain("max");
     });
     it("should support chaining derive and refine", () => {
         const records = schema({
@@ -1129,23 +1131,21 @@ describe("refine", () => {
                 fullName: (row) => `${row.firstName} ${row.lastName}`.trim(),
             },
         })
-            .refine({
-            server: (row) => {
+            .refine((r) => [
+            r("server", (row) => {
                 if (!row.firstName && !row.lastName) {
                     return { path: ["firstName"], message: "Name is required" };
                 }
                 return undefined;
-            },
-        });
+            }),
+        ]);
         const box = createSchemaBox({ records }, { records: {} });
         expect(box.records.deriveDependencies.fullName).toEqual([
             "firstName",
             "lastName",
         ]);
-        expect(box.records.refineDependencies.server).toEqual([
-            "firstName",
-            "lastName",
-        ]);
+        expect(box.records.refineInfo.fieldToGroup).toHaveProperty("firstName");
+        expect(box.records.refineInfo.fieldToGroup).toHaveProperty("lastName");
         const result = box.records.transforms.parseForDb({
             id: 1,
             firstName: "John",

package/dist/vitest/refineRuntime.test.js

@@ -9,14 +9,14 @@ describe("refine runtime behavior", () => {
             min: s.sqlite({ type: "int", nullable: true }).clientInput({ value: null, schema: z.number().nullable() }),
             max: s.sqlite({ type: "int", nullable: true }).clientInput({ value: null, schema: z.number().nullable() }),
             label: s.sqlite({ type: "varchar" }).clientInput({ value: "" }),
-        }).refine({
-            client: (row) => {
+        }).refine((r) => [
+            r("clientInput", (row) => {
                 if (row.min !== null && row.max !== null && row.min >= row.max) {
                     return { path: ["max"], message: "Max must be > min" };
                 }
                 return undefined;
-            },
-            server: (row) => {
+            }),
+            r(["server", "sql"], (row) => {
                 if (row.min !== null && row.max !== null && row.min >= row.max) {
                     return { path: ["max"], message: "Max must be > min" };
                 }
@@ -24,8 +24,8 @@ describe("refine runtime behavior", () => {
                     return { path: ["label"], message: "Label required" };
                 }
                 return undefined;
-            },
-        });
+            }),
+        ]);
         return createSchemaBox({ rules }, { rules: {} });
     }
     it("schemas.clientInput catches client refine", () => {

package/package.json

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