cogsbox-shape 0.5.193 → 0.5.194

package/README.md

@@ -44,7 +44,7 @@ s.sqlite()/s.postgres()/s.mysql()  →  .clientInput()  →  .client()  →  .se
 | `.server(fn)`                     | Server-side validation. Stricter rules before database writes. |
 | `.transform({ toClient, toDb })`  | Converts between database and client representations.          |
 
-Note: `.derive()` is a schema-level method, not chainable on individual fields.
+Note: `.derive()` and `.refine()` are schema-level methods, not chainable on individual fields.
 
 ### 1. SQL — Define Your Database Schema
 
@@ -231,9 +231,71 @@ const users = schema({
 });
 ```
 
-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.
+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
+### 7. Refinement (`.refine()`)
+
+`.refine()` adds cross-field validation rules that the entire row must satisfy. Unlike `.client()`/`.server()` which validate individual fields, `refine` can check relationships between fields.
+
+```typescript
+const events = schema({
+  _tableName: "events",
+  id: s.sqlite({ type: "int", pk: true }),
+  startDate: s.sqlite({ type: "varchar" }).clientInput({ value: "" }),
+  endDate: s.sqlite({ type: "varchar" }).clientInput({ value: "" }),
+  content: s.sqlite({ type: "varchar", nullable: true }).clientInput({
+    value: null,
+    schema: z.string().nullable(),
+  }),
+  isPublished: s.sqlite({ type: "boolean" }).clientInput({ value: false }),
+}).refine({
+  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" });
+    }
+    if (row.isPublished && !row.content) {
+      errors.push({ path: ["content"], message: "Published events must have content" });
+    }
+    return errors.length > 0 ? errors : undefined;
+  },
+});
+
+const box = createSchemaBox({ events }, { events: {} });
+
+// Server refinement runs on parseForDb (before DB writes)
+box.events.transforms.parseForDb({
+  id: 1, startDate: "2024-12-31", endDate: "2024-01-01",
+  content: null, isPublished: false,
+});
+// Throws: "End date must be after start date"
+```
+
+The `refine()` config accepts two optional callbacks:
+
+| Callback | Runs on | Purpose |
+|----------|---------|---------|
+| `server` | `parseForDb()` | Cross-field validation before DB writes |
+| `client` | `clientInput` schema | Cross-field validation on client input |
+
+Each callback 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.
+
+**Chaining**: `refine()` can be chained after `derive()`:
+
+```typescript
+schema({ ... })
+  .derive({ forDb: { fullName: (row) => `${row.firstName} ${row.lastName}` } })
+  .refine({ server: (row) => { ... } });
+```
+
+**Note**: `parsePatchForDb` uses the base schema (without refinement) since partial data may not satisfy cross-field rules.
+
+### Schema Object Structure
 
 The returned schema object has a clear separation of concerns:
 
@@ -247,6 +309,8 @@ schema.generateDefaults; // Function to generate fresh defaults (executes random
 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[] })
 ```
 
 ## 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" | "primaryKeySQL" | "derive";
+type SchemaMetaKey = "_tableName" | "__primaryKeySQL" | "__derives" | "__refinements" | "primaryKeySQL" | "derive" | "refine";
 type SqlConfigOf<TField> = TField extends {
     config: {
         sql: infer TSql;
@@ -54,9 +54,7 @@ type IsDerivedDbField<TTable, TKey> = TTable extends {
             forDb?: infer TForDb;
         };
     };
-} ? TKey extends keyof NonNullable<TForDb> ? true : false : TTable extends {
-    deriveDependencies: infer TDerives;
-} ? TKey extends keyof TDerives ? true : false : false;
+} ? TKey extends keyof NonNullable<TForDb> ? true : false : false;
 type SqlOnlyInput<T> = T extends {
     definition: infer TDefinition;
 } ? Prettify<{

package/dist/schema.d.ts

@@ -205,6 +205,11 @@ export type EnrichFields<T extends ShapeSchema> = {
     [K in keyof T]: K extends "_tableName" ? T[K] : K extends string ? EnrichedField<K, T[K], T> : T[K];
 };
 export declare const SchemaWrapperBrand: unique symbol;
+export type RefinementError = {
+    path: string[];
+    message: string;
+};
+export type RefinementFn<T> = (row: T) => RefinementError | RefinementError[] | undefined | null;
 type PickPrimaryKeys<T extends ShapeSchema> = {
     [K in keyof T as T[K] extends {
         config: {
@@ -237,6 +242,10 @@ 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">>>>>;
+    };
     primaryKeySQL: (definer: (pkFields: PickPrimaryKeys<T>) => string) => SchemaBuilder<T>;
     derive: (derivers: {
         forClient?: {
@@ -246,6 +255,10 @@ 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>;
 };
 export declare function schema<T extends string, U extends ShapeSchema<T>>(schema: U): SchemaBuilder<U>;
 export type RelationType = "hasMany" | "hasOne" | "manyToMany";
@@ -285,6 +298,10 @@ export declare function createSchema<T extends {
     pk: string[] | null;
     clientPk: string[] | null;
     deriveDependencies: Record<string, string[]>;
+    refineDependencies: {
+        server: string[];
+        client: string[];
+    };
     isClientRecord: (record: any) => boolean;
     sqlSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodSqlSchema">>>;
     clientInputSchema: z.ZodObject<Prettify<DeriveSchemaByKey<TActualSchema, "zodClientInputSchema">>>;
@@ -366,6 +383,10 @@ type ResolvedRegistryWithSchemas<S extends Record<string, SchemaWithPlaceholders
         };
         pk: string[] | null;
         clientPk: string[] | null;
+        refineDependencies: {
+            server: string[];
+            client: string[];
+        };
         isClientRecord: (record: any) => boolean;
         generateDefaults: () => Prettify<DeriveDefaults<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
     };
@@ -512,6 +533,10 @@ type RegistryShape = Record<string, {
         defaultValues: any;
         stateType: any;
         deriveDependencies: Record<string, string[]>;
+        refineDependencies: {
+            server: string[];
+            client: string[];
+        };
     };
     transforms: {
         toClient: (dbObject: any) => any;
@@ -523,6 +548,10 @@ type RegistryShape = Record<string, {
     pk: string[] | null;
     clientPk: string[] | null;
     deriveDependencies: Record<string, string[]>;
+    refineDependencies: {
+        server: string[];
+        client: string[];
+    };
     isClientRecord: (record: any) => boolean;
     generateDefaults: () => any;
 }>;
@@ -549,6 +578,11 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
         generateDefaults: () => Resolved[K]["zodSchemas"]["defaultValues"];
         pk: string[] | null;
         clientPk: string[] | null;
+        deriveDependencies: Record<string, string[]>;
+        refineDependencies: {
+            server: string[];
+            client: string[];
+        };
         isClientRecord: (record: any) => boolean;
         nav: NavigationProxy<K & string, Resolved>;
         RelationSelection: NavigationToSelection<NavigationProxy<K & string, Resolved>>;
@@ -574,7 +608,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" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;
@@ -601,7 +635,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" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;
@@ -624,7 +658,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" ? never : K extends keyof T ? T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" | "refine" | "__refinements" ? never : K extends keyof T ? T[K] extends {
         config: {
             sql: {
                 sqlOnly: true;

package/dist/schema.js

@@ -357,6 +357,7 @@ export function schema(schema) {
     enrichedSchema[SchemaWrapperBrand] = true;
     enrichedSchema.__primaryKeySQL = undefined;
     enrichedSchema.__derives = undefined;
+    enrichedSchema.__refinements = undefined;
     enrichedSchema.primaryKeySQL = function (definer) {
         const pkFieldsOnly = {};
         for (const key in schema) {
@@ -374,6 +375,10 @@ export function schema(schema) {
         enrichedSchema.__derives = derivers;
         return enrichedSchema;
     };
+    enrichedSchema.refine = function (refinements) {
+        enrichedSchema.__refinements = refinements;
+        return enrichedSchema;
+    };
     return enrichedSchema;
 }
 function inferDefaultFromZod(zodType, sqlConfig) {
@@ -440,6 +445,7 @@ export function createSchema(schema, relations) {
     let pkKeys = [];
     let clientPkKeys = [];
     const derives = schema.__derives;
+    const refinements = schema.__refinements;
     for (const key in fullSchema) {
         const value = fullSchema[key];
         if (key === "_tableName" ||
@@ -678,22 +684,78 @@ 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 refinedClientInputSchema = finalClientInputSchema;
+    if (refinements?.client) {
+        const clientRefine = refinements.client;
+        refinedClientInputSchema = finalClientInputSchema.superRefine((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,
+                });
+            }
+        });
+    }
     return {
         pk: pkKeys.length ? pkKeys : null,
         clientPk: clientPkKeys.length ? clientPkKeys : null,
         deriveDependencies,
+        refineDependencies,
         isClientRecord,
         sqlSchema: finalSqlSchema,
-        clientInputSchema: finalClientInputSchema,
+        clientInputSchema: refinedClientInputSchema,
         clientSchema: finalClientSchema,
-        serverSchema: finalValidationSchema,
+        serverSchema: refinedValidationSchema,
         defaultValues: defaultValues,
         stateType: {},
         generateDefaults,
         toClient,
         toDb,
         parseForDb: (appData) => {
-            const validData = finalValidationSchema.parse(appData);
+            const validData = refinedValidationSchema.parse(appData);
             return toDb(validData);
         },
         parsePatchForDb: (patchData) => {
@@ -849,6 +911,7 @@ export function createSchemaBox(schemas, resolutions) {
             pk: zodSchemas.pk,
             clientPk: zodSchemas.clientPk,
             deriveDependencies: zodSchemas.deriveDependencies,
+            refineDependencies: zodSchemas.refineDependencies,
             isClientRecord: zodSchemas.isClientRecord,
             generateDefaults: zodSchemas.generateDefaults,
         };
@@ -934,6 +997,7 @@ export function createSchemaBox(schemas, resolutions) {
             pk: entry.pk,
             clientPk: entry.clientPk,
             deriveDependencies: entry.deriveDependencies,
+            refineDependencies: entry.refineDependencies,
             isClientRecord: entry.isClientRecord,
             nav: createNavProxy(tableName, finalRegistry),
             createView: (selection) => {

package/dist/vitest/fullSchema.test.d.ts

@@ -0,0 +1 @@
+export {};