cogsbox-shape 0.5.177 → 0.5.179

package/README.md

@@ -33,16 +33,18 @@ Traditional approaches require defining these layers separately, leading to type
 Define a field by chaining methods. Each step is optional — use only what you need.
 
 ```
-s.sql()  →  .initialState()  →  .client()  →  .server()  →  .transform()
+s.sql()  →  .client()  →  .server()  →  .transform()
+        →  .derive()   →  .sqlOnly()
 ```
 
 | Method                                       | Purpose                                                        |
 | -------------------------------------------- | -------------------------------------------------------------- |
 | `s.sql({ type })`                            | Database column type. The starting point for every field.      |
-| `.initialState({ value, schema, clientPk })` | Default value and type for new records created on the client.  |
-| `.client(fn)`                                | Client-side validation. Overrides the client type if needed.   |
+| `.client({ value, schema })`                 | Client-side validation and default value for new records.      |
 | `.server(fn)`                                | Server-side validation. Stricter rules before database writes. |
-| `.transform({ toClient, toDb })`             | Converts between database and client representations.          |
+| `.transform({ toClient, toDb })`              | Converts between database and client representations.          |
+| `.derive({ field: (row) => computedValue })` | Adds computed fields based on other field values.              |
+| `.sqlOnly`                                   | Marks a field as server-only (not sent to client).             |
 
 ### 1. SQL — Define Your Database Schema
 
@@ -61,66 +63,34 @@ const userSchema = schema({
 
 This generates a Zod schema matching your SQL types exactly.
 
-### 2. Initial State — Defaults for New Records
+### 2. Client — Defaults and Client-Side Validation
 
-When creating new records on the client, you often need different types than what the database stores. `.initialState()` sets the default value and optionally narrows or widens the client type.
+`.client()` sets the default value and client-side validation type for new records.
 
 ```typescript
 const userSchema = schema({
   _tableName: "users",
   // DB stores auto-increment integers, but new records need a temp string ID
-  id: s.sql({ type: "int", pk: true }).initialState({
+  id: s.sql({ type: "int", pk: true }).client({
     value: () => crypto.randomUUID(),
     schema: z.string(),
-    clientPk: true, // Explicitly marks this as a client PK, auto-creating a union type
   }),
-  // Client type becomes: string | number (union of SQL + initialState)
+  // Client type becomes: string | number (union of SQL + client)
   // Default value: a generated UUID string
-});
-```
-
-If the type you pass to `.initialState()` matches the SQL type, no union is created:
-
-```typescript
-count: s.sql({ type: "int" }).initialState({ value: 0 }),
-// Client type: number (no union, same type)
-// Default value: 0
-```
-
-### 3. Client — Client-Side Validation
 
-The client schema is automatically derived as a union of the SQL type (data fetched from the database) and the initial state type (data created on the client). `.client()` lets you override this to add client-side validation rules or declare a completely different type.
+  // Simple default without type override
+  name: s.sql({ type: "varchar" }).client({ value: "Anonymous" }),
+  // Client type: string (inherits from SQL)
+  // Default value: "Anonymous"
 
-```typescript
-// Without .client() — the type is inferred automatically
-id: s.sql({ type: "int", pk: true }).initialState({
-  value: () => crypto.randomUUID(),
-  schema: z.string(),
-}),
-// Client type: string | number
-// (string from initialState + number from SQL)
-
-// With .client() — add validation rules
-name: s
-  .sql({ type: "varchar" })
-  .client(({ sql }) => sql.min(2).max(100)),
-// Client type: string (with min/max validation)
-
-// With .client() — declare a different type entirely
-// Pair with .transform() to convert between them
-isActive: s
-  .sql({ type: "int" })
-  .client(() => z.boolean())
-  .transform({
-    toClient: (dbValue) => dbValue === 1,
-    toDb: (clientValue) => (clientValue ? 1 : 0),
-  }),
-// Client type: boolean (DB stores 0/1, client works with true/false)
+  // Type-only override (no default value change)
+  count: s.sql({ type: "int" }).client(() => z.number().min(0)),
+  // Client type: number (with min validation)
+  // Default value: inferred from type (0 for number)
+});
 ```
 
-When `.client()` overrides the type without `.initialState()`, the default value is inferred from the client schema (e.g., `boolean` → `false`, `string` → `""`).
-
-### 4. Server — Server-Side Validation
+### 3. Server — Server-Side Validation
 
 `.server()` adds validation rules that run at the server boundary before database writes. It builds on the client schema, adding stricter constraints.
 
@@ -146,7 +116,7 @@ name: s
   .server(({ client }) => client.min(2, "Too short")),
 ```
 
-### 5. Transform — Convert Between Layers
+### 4. Transform — Convert Between Layers
 
 `.transform()` defines bidirectional conversion functions. These run on the server when reading from or writing to the database.
 
@@ -162,6 +132,84 @@ status: s
 
 Transforms are optional — only needed when the client type differs from the SQL type.
 
+### 6. Derive — Computed Fields
+
+`.derive()` adds computed fields that are calculated from other values in the row. These are:
+- Available in client schema and defaults
+- NOT stored in the database (computed at runtime)
+- Useful for display-only fields, combinations, or formatted values
+
+```typescript
+const userSchema = schema({
+  _tableName: "users",
+  firstName: s.sql({ type: "varchar" }).client({ value: "John" }),
+  lastName: s.sql({ type: "varchar" }).client({ value: "Doe" }),
+  // Define placeholder for derived field
+  fullName: s.client(""),  // Required: tells schema this field exists on client
+}).derive({
+  fullName: (row) => `${row.firstName} ${row.lastName}`,
+});
+
+// Now defaults and toClient include the computed value
+const defaults = box.users.defaults;
+// { firstName: "John", lastName: "Doe", fullName: "John Doe" }
+```
+
+The derived field's default value is computed from other defaults at initialization time.
+
+### 7. sqlOnly — Server-Only Fields
+
+`.sql({ sqlOnly: true })` marks a field as server-only:
+- Included in SQL schema (stored in DB)
+- Excluded from client schema (not sent to client)
+- Useful for internal tokens, computed scores, or sensitive data
+
+```typescript
+const userSchema = schema({
+  _tableName: "users",
+  id: s.sql({ type: "int", pk: true }),
+  email: s.sql({ type: "varchar" }),
+  internalToken: s.sql({ type: "varchar", sqlOnly: true }),
+  trustScore: s.sql({ type: "int", sqlOnly: true }),
+});
+
+// Client schema: { id, email } — internalToken and trustScore excluded
+// SQL schema: { id, email, internalToken, trustScore } — all fields
+// Defaults: { id: 0, email: "" } — sqlOnly fields excluded
+```
+
+### 8. Client-Only Fields
+
+Use `s.client()` without `s.sql()` to define fields that exist only on the client:
+
+```typescript
+const orderSchema = schema({
+  _tableName: "orders",
+  id: s.sql({ type: "int", pk: true }),
+  total: s.sql({ type: "int" }).client({ value: 0 }),
+  // Client-only: computed from other fields, not stored
+  formattedTotal: s.client(""),
+}).derive({
+  formattedTotal: (row) => `$${(row.total / 100).toFixed(2)}`,
+});
+```
+
+### Schema Object Structure
+
+The returned schema object has a clear separation of concerns:
+
+```typescript
+const schema = createSchema(mySchema);
+
+schema.schemas;           // { sqlSchema, clientSchema, serverSchema } — Zod schemas
+schema.transforms;        // { toClient, toDb, parseForDb, parseFromDb } — transformations
+schema.defaults;          // Default values for forms
+schema.generateDefaults; // Function to generate fresh 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
+```
+
 ## Using Schemas
 
 ### Single Schema with `createSchema`
@@ -173,10 +221,9 @@ import { s, schema, createSchema } from "cogsbox-shape";
 
 const contactSchema = schema({
   _tableName: "contacts",
-  id: s.sql({ type: "int", pk: true }).initialState({
+  id: s.sql({ type: "int", pk: true }).client({
     value: () => `new_${crypto.randomUUID().slice(0, 8)}`,
     schema: z.string(),
-    clientPk: true,
   }),
   name: s.sql({ type: "varchar" }).server(({ sql }) => sql.min(2)),
   email: s.sql({ type: "varchar" }).server(({ sql }) => sql.email()),
@@ -189,15 +236,14 @@ const contactSchema = schema({
     }),
 });
 
-const {
-  clientSchema, // Zod schema for client-side validation
-  serverSchema, // Zod schema with .server() rules
-  sqlSchema, // Zod schema matching DB column types
-  defaultValues, // Typed defaults matching clientSchema
-  generateDefaults, // Generates fresh defaults (executes randomizers/dates)
-  parseForDb, // Validates client app data & transforms to DB format
-  parseFromDb, // Transforms DB data & validates to Client format
-} = createSchema(contactSchema);
+const schema = createSchema(contactSchema);
+
+// Access schemas directly
+const { clientSchema, serverSchema, sqlSchema } = schema;
+const { defaultValues, generateDefaults } = schema;
+
+// Transforms for converting between layers
+const { toClient, toDb, parseForDb, parseFromDb } = schema.transforms;
 
 // Use in a form
 const [data, setData] = useState(generateDefaults());
@@ -252,11 +298,19 @@ const box = createSchemaBox({ users, posts }, (s) => ({
 Base schemas **exclude relations** by default, preventing circular dependencies:
 
 ```typescript
-const { schemas, defaults } = box.users;
+const { schemas, defaults, transforms, pk, clientPk } = box.users;
 
 type UserClient = z.infer<typeof schemas.client>;
 // { id: number; name: string; }
 // No 'posts' — relations are excluded from base schemas
+
+// Convert data between layers
+const dbRow = transforms.toDb(clientData);
+const clientData = transforms.toClient(dbRow);
+
+// Validate and convert in one step
+const dbRow = transforms.parseForDb(appData);
+const clientData = transforms.parseFromDb(dbRow);
 ```
 
 ### 4. Create Views to Include Relations
@@ -275,6 +329,8 @@ type UserWithPosts = z.infer<typeof userWithPosts.schemas.client>;
 //   posts: { id: number; title: string; authorId: number; }[]
 // }
 
-const defaults = userWithPosts.defaults;
-// { id: 0, name: '', posts:
+// Views also have transforms for the selected fields
+const { defaults, transforms } = userWithPosts;
+// transforms.apply() handles nested relations automatically
+```
 ```

package/dist/schema.d.ts

@@ -33,6 +33,7 @@ type BaseConfig = {
     nullable?: boolean;
     pk?: true;
     field?: string;
+    sqlOnly?: true;
 };
 type SQLToZodType<T extends SQLType, TDefault extends boolean> = T["pk"] extends true ? TDefault extends true ? z.ZodString : z.ZodNumber : T["nullable"] extends true ? T["type"] extends "varchar" | "char" | "text" | "longtext" ? z.ZodNullable<z.ZodString> : T["type"] extends "int" ? z.ZodNullable<z.ZodNumber> : T["type"] extends "boolean" ? z.ZodNullable<z.ZodBoolean> : T["type"] extends "date" | "datetime" | "timestamp" ? T extends {
     default: "CURRENT_TIMESTAMP";
@@ -41,45 +42,59 @@ type SQLToZodType<T extends SQLType, TDefault extends boolean> = T["pk"] extends
 } ? TDefault extends true ? never : z.ZodDate : z.ZodDate : never;
 type ZodTypeFromPrimitive<T> = T extends string ? z.ZodString : T extends number ? z.ZodNumber : T extends boolean ? z.ZodBoolean : T extends Date ? z.ZodDate : z.ZodAny;
 type CollapsedUnion<A extends z.ZodTypeAny, B extends z.ZodTypeAny> = A extends B ? (B extends A ? A : z.ZodUnion<[A, B]>) : z.ZodUnion<[A, B]>;
-export interface IBuilderMethods<T extends DbConfig, TSql extends z.ZodTypeAny, TNew extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> {
-    initialState<const TValue>(options: {
+export interface IBuilderMethods<T extends DbConfig, TSql extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> {
+    client<const TValue>(options: {
         value: TValue | ((tools: {
             uuid: () => string;
         }) => TValue);
         schema?: never;
         clientPk?: boolean | ((val: any) => boolean);
-    }): Prettify<Builder<"new", T, TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>, TValue extends () => infer R ? R : TValue, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>>>;
-    initialState<const TSchema extends z.ZodTypeAny>(options: {
+    }): Prettify<Builder<"client", T, TSql, TValue extends () => infer R ? R : TValue, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>>>;
+    client<const TSchema extends z.ZodTypeAny>(options: {
         value?: never;
         schema: TSchema;
         clientPk?: boolean | ((val: any) => boolean);
-    }): Prettify<Builder<"new", T, TSql, TSchema, z.infer<TSchema>, CollapsedUnion<TSql, TSchema>, CollapsedUnion<TSql, TSchema>>>;
-    initialState<const TValue, const TSchema extends z.ZodTypeAny>(options: {
+    }): Prettify<Builder<"client", T, TSql, z.infer<TSchema>, CollapsedUnion<TSql, TSchema>, CollapsedUnion<TSql, TSchema>>>;
+    client<const TSchema extends z.ZodTypeAny>(options: {
+        value?: never;
+        schema: TSchema | ((tools: any) => TSchema);
+        clientPk?: boolean | ((val: any) => boolean);
+    }): Prettify<Builder<"client", T, TSql, z.infer<TSchema>, CollapsedUnion<TSql, TSchema>, CollapsedUnion<TSql, TSchema>>>;
+    client<const TValue>(options: {
+        value: TValue | ((tools: {
+            uuid: () => string;
+        }) => TValue);
+        schema?: never;
+        clientPk?: boolean | ((val: any) => boolean);
+    }): Prettify<Builder<"client", T, TSql, TValue extends () => infer R ? R : TValue, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>, CollapsedUnion<TSql, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>>>;
+    client(options: {
+        value?: never;
+        schema: (tools: any) => z.ZodTypeAny;
+    }): Prettify<Builder<"client", T, TSql, unknown, z.ZodTypeAny, z.ZodTypeAny>>;
+    client<const TValue, const TSchema extends z.ZodTypeAny>(options: {
         value: TValue | ((tools: {
             uuid: () => string;
         }) => TValue);
         schema: TSchema | ((base: ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>) => TSchema);
         clientPk?: boolean | ((val: any) => boolean);
-    }): Prettify<Builder<"new", T, TSql, TSchema, z.infer<TSchema>, CollapsedUnion<TSql, TSchema>, CollapsedUnion<TSql, TSchema>>>;
+    }): Prettify<Builder<"client", T, TSql, TValue extends () => infer R ? R : TValue, CollapsedUnion<TSql, TSchema>, CollapsedUnion<TSql, TSchema>>>;
+    client<TClientNext extends z.ZodTypeAny>(schema: ((tools: {
+        sql: TSql;
+    }) => TClientNext) | TClientNext): Prettify<Builder<"client", T, TSql, TInitialValue, TClientNext, TClientNext>>;
     reference: <TRefSchema extends {
         _tableName: string;
     }>(fieldGetter: () => any) => Builder<"sql", T & {
         references: typeof fieldGetter;
-    }, TSql, TNew, TInitialValue, TClient, TValidation>;
-    client: <TClientNext extends z.ZodTypeAny>(schema: ((tools: {
-        sql: TSql;
-        initialState: TNew;
-    }) => TClientNext) | TClientNext) => Prettify<Builder<"client", T, TSql, TNew, TInitialValue, TClientNext, TClientNext>>;
+    }, TSql, TInitialValue, TClient, TValidation>;
     server: <TValidationNext extends z.ZodTypeAny>(schema: ((tools: {
         sql: TSql;
-        initialState: TNew;
         client: TClient;
-    }) => TValidationNext) | TValidationNext) => Prettify<Builder<"server", T, TSql, TNew, TInitialValue, TClient, TValidationNext>>;
+    }) => TValidationNext) | TValidationNext) => Prettify<Builder<"server", T, TSql, TInitialValue, TClient, TValidationNext>>;
     transform: (transforms: {
         toClient: (dbValue: z.infer<TSql>) => z.infer<TClient>;
         toDb: (clientValue: z.infer<TClient>) => z.infer<TSql>;
     }) => {
-        config: Prettify<BuilderConfig<T, TSql, TNew, TInitialValue, TClient, TValidation>> & {
+        config: Prettify<BuilderConfig<T, TSql, TInitialValue, TClient, TValidation>> & {
             transforms: typeof transforms;
         };
     };
@@ -99,35 +114,32 @@ export type RelationConfig<T extends Schema<any>> = (BaseRelationConfig<T> & {
 }) | (BaseRelationConfig<T> & {
     type: "manyToMany";
 });
-type Stage = "sql" | "relation" | "new" | "client" | "server" | "done";
+type Stage = "sql" | "relation" | "client" | "server" | "done";
 type StageMethods = {
-    sql: "initialState" | "client" | "server" | "transform" | "reference";
-    relation: "server" | "transform";
-    new: "client" | "server" | "transform";
+    sql: "client" | "server" | "transform" | "reference";
+    relation: "client" | "server" | "transform";
     client: "server" | "transform";
     server: "transform";
     done: never;
 };
-type BuilderConfig<T extends DbConfig, TSql extends z.ZodTypeAny, TNew extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> = {
+type BuilderConfig<T extends DbConfig, TSql extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> = {
     sql: T;
     zodSqlSchema: TSql;
-    zodNewSchema: TNew;
     initialValue: TInitialValue;
     zodClientSchema: TClient;
     zodValidationSchema: TValidation;
     clientTransform?: (schema: z.ZodTypeAny) => z.ZodTypeAny;
     validationTransform?: (schema: z.ZodTypeAny) => z.ZodTypeAny;
 };
-export type Builder<TStage extends Stage, T extends DbConfig, TSql extends z.ZodTypeAny, TNew extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> = {
+export type Builder<TStage extends Stage, T extends DbConfig, TSql extends z.ZodTypeAny, TInitialValue, TClient extends z.ZodTypeAny, TValidation extends z.ZodTypeAny> = {
     config: {
         sql: T;
         zodSqlSchema: TSql;
-        zodNewSchema: TNew;
         initialValue: TInitialValue;
         zodClientSchema: TClient;
         zodValidationSchema: TValidation;
     };
-} & Pick<IBuilderMethods<T, TSql, TNew, TInitialValue, TClient, TValidation>, StageMethods[TStage]>;
+} & Pick<IBuilderMethods<T, TSql, TInitialValue, TClient, TValidation>, StageMethods[TStage]>;
 type HasManyDefault = true | undefined | [] | {
     count: number;
 };
@@ -137,11 +149,11 @@ export type Reference<TGetter extends () => any> = {
     getter: TGetter;
 };
 interface ShapeAPI {
-    initialState: <const TValue>(value: TValue | ((tools: {
+    client: <const TValue>(value: TValue | ((tools: {
         uuid: () => string;
-    }) => TValue)) => Builder<"new", null, z.ZodUndefined, // No SQL schema
-    ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>, TValue extends () => infer R ? R : TValue, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>;
-    sql: <const T extends SQLType>(sqlConfig: T) => Builder<"sql", T, SQLToZodType<T, false>, SQLToZodType<T, false>, z.infer<SQLToZodType<T, false>>, SQLToZodType<T, false>, SQLToZodType<T, false>>;
+    }) => TValue)) => Builder<"client", null, z.ZodUndefined, // No SQL schema
+    TValue extends () => infer R ? R : TValue, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>, ZodTypeFromPrimitive<TValue extends () => infer R ? R : TValue>>;
+    sql: <const T extends SQLType>(sqlConfig: T) => Builder<"sql", T, SQLToZodType<T, false>, z.infer<SQLToZodType<T, false>>, SQLToZodType<T, false>, SQLToZodType<T, false>>;
     reference: <TGetter extends () => any>(getter: TGetter) => Reference<TGetter>;
     hasMany: <T extends HasManyDefault>(config?: T) => PlaceholderRelation<"hasMany">;
     hasOne: (config?: HasOneDefault) => PlaceholderRelation<"hasOne">;
@@ -173,7 +185,9 @@ type PickPrimaryKeys<T extends ShapeSchema> = {
 };
 type SchemaBuilder<T extends ShapeSchema> = Prettify<EnrichFields<T>> & {
     __primaryKeySQL?: string;
+    __derives?: 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>;
 };
 export declare function schema<T extends string, U extends ShapeSchema<T>>(schema: U): SchemaBuilder<U>;
 export type RelationType = "hasMany" | "hasOne" | "manyToMany";
@@ -267,7 +281,7 @@ type ResolveField<Field, Resolution> = Field extends PlaceholderReference ? Reso
     type: "belongsTo";
 } : RelType extends "manyToMany" ? BaseRelationConfig<TargetSchema> & {
     type: "manyToMany";
-} : never, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>, RelType extends "hasMany" | "manyToMany" ? any[] : any, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>> : never : never : Field;
+} : never, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>, RelType extends "hasMany" | "manyToMany" ? any[] : any, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>, RelType extends "hasMany" | "manyToMany" ? z.ZodArray<z.ZodObject<any>> : z.ZodObject<any>> : never : never : Field;
 type ResolveSchema<Schema extends SchemaWithPlaceholders, Resolutions extends Record<string, any>> = {
     [K in keyof Schema]: K extends keyof Resolutions ? ResolveField<Schema[K], Resolutions[K]> : Schema[K];
 };
@@ -280,15 +294,17 @@ type ResolvedRegistryWithSchemas<S extends Record<string, SchemaWithPlaceholders
             serverSchema: z.ZodObject<Prettify<DeriveSchemaByKey<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>, "zodValidationSchema">>>;
             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] : {}) : {}>>>;
+        };
+        transforms: {
             toClient: (dbObject: any) => any;
             toDb: (clientObject: any) => any;
             parseForDb: (appData: any) => any;
             parseFromDb: (dbData: any) => any;
-            pk: string[] | null;
-            clientPk: string[] | null;
-            isClientRecord: (record: any) => boolean;
-            generateDefaults: () => Prettify<DeriveDefaults<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
         };
+        pk: string[] | null;
+        clientPk: string[] | null;
+        isClientRecord: (record: any) => boolean;
+        generateDefaults: () => Prettify<DeriveDefaults<ResolveSchema<S[K], K extends keyof R ? (R[K] extends object ? R[K] : {}) : {}>>>;
     };
 };
 type IsRelationField<Field> = Field extends {
@@ -313,7 +329,8 @@ type GetRelationRegistryKey<Field, TRegistry extends RegistryShape> = Field exte
 type OmitRelationFields<Shape, RawSchema> = Omit<Shape, {
     [K in keyof Shape]: K extends keyof RawSchema ? IsRelationField<RawSchema[K]> extends true ? K : never : never;
 }[keyof Shape]>;
-type _DeriveViewShape<TTableName extends keyof TRegistry, TSelection, TRegistry extends RegistryShape, TKey extends "clientSchema" | "serverSchema", Depth extends any[] = []> = Depth["length"] extends 10 ? any : TRegistry[TTableName]["zodSchemas"][TKey] extends z.ZodObject<infer BaseShape> ? TSelection extends Record<string, any> ? Prettify<OmitRelationFields<BaseShape, TRegistry[TTableName]["rawSchema"]> & {
+type _DeriveViewShape<TTableName extends keyof TRegistry, TSelection, TRegistry extends RegistryShape, TKey extends "clientSchema" | "serverSchema" | "sqlSchema", Depth extends any[] = []> = Depth["length"] extends 10 ? any : TKey extends "sqlSchema" ? TRegistry[TTableName]["zodSchemas"]["sqlSchema"] extends z.ZodObject<infer BaseShape> ? _DeriveViewShapeInner<BaseShape, TTableName, TSelection, TRegistry, TKey, Depth> : never : TRegistry[TTableName]["zodSchemas"][TKey] extends z.ZodObject<infer BaseShape> ? _DeriveViewShapeInner<BaseShape, TTableName, TSelection, TRegistry, TKey, Depth> : never;
+type _DeriveViewShapeInner<BaseShape, TTableName extends keyof TRegistry, TSelection, TRegistry extends RegistryShape, TKey extends "clientSchema" | "serverSchema" | "sqlSchema", Depth extends any[] = []> = TSelection extends Record<string, any> ? Prettify<OmitRelationFields<BaseShape, TRegistry[TTableName]["rawSchema"]> & {
     [K in keyof TSelection & keyof TRegistry[TTableName]["rawSchema"] as IsRelationField<TRegistry[TTableName]["rawSchema"][K]> extends true ? K : never]: GetRelationRegistryKey<TRegistry[TTableName]["rawSchema"][K], TRegistry> extends infer TargetKey ? TargetKey extends keyof TRegistry ? TRegistry[TTableName]["rawSchema"][K] extends {
         config: {
             sql: {
@@ -327,7 +344,7 @@ type _DeriveViewShape<TTableName extends keyof TRegistry, TSelection, TRegistry
         ...Depth,
         1
     ]>>> : never : never : never;
-}> : OmitRelationFields<BaseShape, TRegistry[TTableName]["rawSchema"]> : never;
+}> : OmitRelationFields<BaseShape, TRegistry[TTableName]["rawSchema"]>;
 type DeriveViewDefaults<TTableName extends keyof TRegistry, TSelection, TRegistry extends RegistryShape, Depth extends any[] = []> = Prettify<TRegistry[TTableName]["zodSchemas"]["defaultValues"] & (TSelection extends Record<string, any> ? {
     [K in keyof TSelection & keyof TRegistry[TTableName]["rawSchema"] as IsRelationField<TRegistry[TTableName]["rawSchema"][K]> extends true ? K : never]: TRegistry[TTableName]["rawSchema"][K] extends {
         config: {
@@ -353,11 +370,11 @@ export type DeriveViewResult<TTableName extends keyof TRegistry, TSelection, TRe
         server: z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "serverSchema">>;
     };
     transforms: {
-        toClient: TRegistry[TTableName]["zodSchemas"]["toClient"];
-        toDb: TRegistry[TTableName]["zodSchemas"]["toDb"];
+        toClient: TRegistry[TTableName]["transforms"]["toClient"];
+        toDb: TRegistry[TTableName]["transforms"]["toDb"];
+        parseForDb: (appData: z.input<z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "serverSchema">>>) => z.infer<z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "sqlSchema">>>;
+        parseFromDb: (dbData: Partial<z.infer<z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "sqlSchema">>>>) => z.infer<z.ZodObject<_DeriveViewShape<TTableName, TSelection, TRegistry, "clientSchema">>>;
     };
-    parseForDb: (appData: z.input<TRegistry[TTableName]["zodSchemas"]["serverSchema"]>) => z.infer<TRegistry[TTableName]["zodSchemas"]["sqlSchema"]>;
-    parseFromDb: (dbData: Partial<z.infer<TRegistry[TTableName]["zodSchemas"]["sqlSchema"]>>) => z.infer<TRegistry[TTableName]["zodSchemas"]["clientSchema"]>;
     defaults: DeriveViewDefaults<TTableName, TSelection, TRegistry>;
     pk: string[] | null;
     clientPk: string[] | null;
@@ -397,15 +414,17 @@ type RegistryShape = Record<string, {
         serverSchema: z.ZodObject<any>;
         defaultValues: any;
         stateType: any;
+    };
+    transforms: {
         toClient: (dbObject: any) => any;
         toDb: (clientObject: any) => any;
         parseForDb: (appData: any) => any;
         parseFromDb: (dbData: any) => any;
-        pk: string[] | null;
-        clientPk: string[] | null;
-        isClientRecord: (record: any) => boolean;
-        generateDefaults: () => any;
     };
+    pk: string[] | null;
+    clientPk: string[] | null;
+    isClientRecord: (record: any) => boolean;
+    generateDefaults: () => any;
 }>;
 type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R extends ResolutionMap<S>, Resolved extends RegistryShape = ResolvedRegistryWithSchemas<S, R> extends RegistryShape ? ResolvedRegistryWithSchemas<S, R> : RegistryShape> = {
     [K in keyof Resolved]: {
@@ -419,9 +438,9 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
         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"]>;
+            parseForDb: (appData: z.input<Resolved[K]["zodSchemas"]["serverSchema"]>) => z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>;
+            parseFromDb: (dbData: Partial<z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>>) => z.infer<Resolved[K]["zodSchemas"]["clientSchema"]>;
         };
-        parseForDb: (appData: z.input<Resolved[K]["zodSchemas"]["serverSchema"]>) => z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>;
-        parseFromDb: (dbData: Partial<z.infer<Resolved[K]["zodSchemas"]["sqlSchema"]>>) => z.infer<Resolved[K]["zodSchemas"]["clientSchema"]>;
         defaults: Resolved[K]["zodSchemas"]["defaultValues"];
         stateType: Resolved[K]["zodSchemas"]["stateType"];
         generateDefaults: () => Resolved[K]["zodSchemas"]["defaultValues"];
@@ -434,20 +453,7 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
         __registry: Resolved;
     };
 };
-export declare function createSchemaBox<S extends Record<string, SchemaWithPlaceholders>, R extends ResolutionMap<S>>(schemas: S, resolver: (proxy: SchemaProxy<S>) => R): CreateSchemaBoxReturn<S, R>;
-type SchemaProxy<S extends Record<string, SchemaWithPlaceholders>> = {
-    [K in keyof S]: {
-        [F in keyof S[K] as F extends "_tableName" ? never : F]: S[K][F] extends {
-            config: infer Config;
-        } ? S[K][F] & {
-            __meta: {
-                _key: F;
-                _fieldType: S[K][F];
-            };
-            __parentTableType: S[K];
-        } : S[K][F];
-    };
-};
+export declare function createSchemaBox<S extends Record<string, SchemaWithPlaceholders>, R extends ResolutionMap<S>>(schemas: S, resolutions: R): CreateSchemaBoxReturn<S, R>;
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
@@ -465,7 +471,13 @@ type GetDbKey<K, Field> = Field extends Reference<infer TGetter> ? ReturnType<TG
     };
 } ? string extends F ? K : F : K;
 type DeriveSchemaByKey<T, Key extends "zodSqlSchema" | "zodClientSchema" | "zodValidationSchema", Depth extends any[] = []> = Depth["length"] extends 10 ? any : {
-    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" ? never : K extends keyof T ? T[K] extends Reference<any> ? Key extends "zodSqlSchema" ? GetDbKey<K, T[K]> : K : T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" ? never : K extends keyof T ? T[K] extends {
+        config: {
+            sql: {
+                sqlOnly: true;
+            };
+        };
+    } ? Key extends "zodSqlSchema" ? GetDbKey<K, T[K]> : never : T[K] extends Reference<any> ? Key extends "zodSqlSchema" ? GetDbKey<K, T[K]> : K : T[K] extends {
         config: {
             sql: {
                 type: "hasMany" | "manyToMany" | "hasOne" | "belongsTo";
@@ -482,7 +494,13 @@ type DeriveSchemaByKey<T, Key extends "zodSqlSchema" | "zodClientSchema" | "zodV
     } ? 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" ? never : K extends keyof T ? T[K] extends Reference<any> ? K : T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" ? never : K extends keyof T ? T[K] extends {
+        config: {
+            sql: {
+                sqlOnly: true;
+            };
+        };
+    } ? never : T[K] extends Reference<any> ? K : T[K] extends {
         config: {
             sql: {
                 type: "hasMany" | "manyToMany" | "hasOne" | "belongsTo";
@@ -494,15 +512,18 @@ type DeriveDefaults<T, Depth extends any[] = []> = Prettify<Depth["length"] exte
         };
     } ? D extends () => infer R ? R : D : never : T[K] extends {
         config: {
-            zodNewSchema: infer TNew;
-            zodSqlSchema: infer TSql;
             zodClientSchema: infer TClient extends z.ZodTypeAny;
-            initialValue: infer D;
         };
-    } ? TNew extends TSql ? z.infer<TClient> : D extends () => infer R ? R : D : never;
+    } ? 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" ? never : K extends keyof T ? T[K] extends Reference<any> ? K : T[K] extends {
+    [K in keyof T as K extends "_tableName" | typeof SchemaWrapperBrand | "__primaryKeySQL" | "primaryKeySQL" | "derive" | "__derives" ? never : K extends keyof T ? T[K] extends {
+        config: {
+            sql: {
+                sqlOnly: true;
+            };
+        };
+    } ? never : T[K] extends Reference<any> ? K : T[K] extends {
         config: {
             sql: {
                 type: "hasMany" | "manyToMany" | "hasOne" | "belongsTo";

package/dist/schema.js

@@ -1,7 +1,6 @@
 import { z } from "zod";
 import { v4 as uuid } from "uuid";
 export const isFunction = (fn) => typeof fn === "function";
-// Function to create a properly typed current timestamp config
 export function currentTimeStamp() {
     return {
         default: "CURRENT_TIMESTAMP",
@@ -9,9 +8,8 @@ export function currentTimeStamp() {
     };
 }
 export const s = {
-    initialState: (value) => {
+    client: (value) => {
         const actualValue = isFunction(value) ? value({ uuid }) : value;
-        // Infer the Zod type from the primitive value
         let inferredZodType;
         if (typeof actualValue === "string") {
             inferredZodType = z.string();
@@ -32,10 +30,9 @@ export const s = {
             inferredZodType = z.any();
         }
         return createBuilder({
-            stage: "new",
+            stage: "client",
             sqlConfig: null,
             sqlZod: z.undefined(),
-            newZod: inferredZodType,
             initialValue: actualValue,
             clientZod: inferredZodType,
             validationZod: inferredZodType,
@@ -56,7 +53,7 @@ export const s = {
     hasOne: (config) => ({
         __type: "placeholder-relation",
         relationType: "hasOne",
-        defaultConfig: config, // This line is the crucial fix
+        defaultConfig: config,
     }),
     manyToMany: (config) => ({
         __type: "placeholder-relation",
@@ -96,7 +93,6 @@ export const s = {
             stage: "sql",
             sqlConfig: sqlConfig,
             sqlZod: sqlZodType,
-            newZod: sqlZodType,
             initialValue: inferDefaultFromZod(sqlZodType, sqlConfig),
             clientZod: sqlZodType,
             validationZod: sqlZodType,
@@ -109,7 +105,6 @@ function createBuilder(config) {
         config: {
             sql: config.sqlConfig,
             zodSqlSchema: config.sqlZod,
-            zodNewSchema: config.newZod,
             initialValue: config.initialValue ||
                 inferDefaultFromZod(config.clientZod, config.sqlConfig),
             zodClientSchema: config.clientZod,
@@ -117,138 +112,163 @@ function createBuilder(config) {
             clientTransform: config.clientTransform,
             validationTransform: config.validationTransform,
         },
-        initialState: (options) => {
-            if (completedStages.has("new")) {
-                throw new Error("initialState() can only be called once in the chain");
+        reference: (fieldGetter) => {
+            return createBuilder({
+                ...config,
+                sqlConfig: {
+                    ...config.sqlConfig,
+                    reference: fieldGetter,
+                },
+            });
+        },
+        client: (...args) => {
+            if (completedStages.has("client")) {
+                throw new Error("client() can only be called once in the chain");
+            }
+            if (completedStages.has("server")) {
+                throw new Error("client() must be called before server()");
+            }
+            const newCompletedStages = new Set(completedStages);
+            newCompletedStages.add("client");
+            let optionsOrSchema = args[0];
+            if (config.stage === "relation") {
+                const assert = typeof optionsOrSchema === "function" ||
+                    optionsOrSchema instanceof z.ZodType
+                    ? optionsOrSchema
+                    : optionsOrSchema?.schema;
+                return createBuilder({
+                    ...config,
+                    stage: "client",
+                    completedStages: newCompletedStages,
+                    clientTransform: (baseSchema) => {
+                        if (isFunction(assert)) {
+                            return assert({ sql: baseSchema });
+                        }
+                        return assert;
+                    },
+                });
+            }
+            let isDirectShortcut = false;
+            let isValueAndSchemaShortcut = false;
+            let options = {};
+            if (optionsOrSchema !== undefined &&
+                typeof optionsOrSchema === "function") {
+                if (args.length === 2 && isFunction(args[1])) {
+                    isValueAndSchemaShortcut = true;
+                    options = {
+                        schema: optionsOrSchema,
+                        value: args[1],
+                    };
+                }
+                else {
+                    options = { schema: optionsOrSchema };
+                    isDirectShortcut = true;
+                }
+            }
+            else if (optionsOrSchema !== undefined &&
+                typeof optionsOrSchema === "object" &&
+                !("_def" in optionsOrSchema) &&
+                !("parse" in optionsOrSchema) &&
+                (optionsOrSchema.value !== undefined ||
+                    optionsOrSchema.schema !== undefined ||
+                    optionsOrSchema.clientPk !== undefined)) {
+                options = optionsOrSchema;
+            }
+            else if (optionsOrSchema !== undefined) {
+                options = { schema: optionsOrSchema };
+                isDirectShortcut = true;
             }
             const { value, schema: schemaOrModifier, clientPk } = options;
-            let actualValue;
+            let actualValue = config.initialValue;
             let finalSchema;
-            // 1. Determine the actual value
             if (value !== undefined) {
                 actualValue = isFunction(value) ? value({ uuid }) : value;
             }
             else if (schemaOrModifier &&
                 typeof schemaOrModifier === "object" &&
                 "_def" in schemaOrModifier) {
-                // If only a schema is provided, infer the default from it
-                actualValue = inferDefaultFromZod(schemaOrModifier, config.sqlConfig);
+                if (config.sqlZod instanceof z.ZodUndefined ||
+                    actualValue === undefined) {
+                    actualValue = inferDefaultFromZod(schemaOrModifier, config.sqlConfig);
+                }
             }
-            // 2. Determine the final schema
             let baseSchema;
             if (schemaOrModifier &&
                 typeof schemaOrModifier === "object" &&
                 "_def" in schemaOrModifier) {
-                // A raw Zod schema was passed
                 finalSchema = schemaOrModifier;
             }
             else {
-                // Base schema must be inferred from the value type
-                if (typeof actualValue === "string")
-                    baseSchema = z.string();
-                else if (typeof actualValue === "number")
-                    baseSchema = z.number();
-                else if (typeof actualValue === "boolean")
-                    baseSchema = z.boolean();
-                else if (actualValue instanceof Date)
-                    baseSchema = z.date();
-                else if (actualValue === null)
-                    baseSchema = z.null();
-                else
-                    baseSchema = z.any();
+                if (value !== undefined) {
+                    if (typeof actualValue === "string")
+                        baseSchema = z.string();
+                    else if (typeof actualValue === "number")
+                        baseSchema = z.number();
+                    else if (typeof actualValue === "boolean")
+                        baseSchema = z.boolean();
+                    else if (actualValue instanceof Date)
+                        baseSchema = z.date();
+                    else if (actualValue === null)
+                        baseSchema = z.null();
+                    else
+                        baseSchema = z.any();
+                }
+                else {
+                    baseSchema = config.clientZod;
+                }
                 if (isFunction(schemaOrModifier)) {
-                    // A modifier function was passed
-                    finalSchema = schemaOrModifier(baseSchema);
+                    if (isDirectShortcut) {
+                        finalSchema = schemaOrModifier({ sql: config.sqlZod });
+                    }
+                    else {
+                        finalSchema = schemaOrModifier(baseSchema);
+                    }
                 }
                 else {
-                    // No schema/modifier, use the inferred base schema
                     finalSchema = baseSchema;
                 }
             }
-            const newCompletedStages = new Set(completedStages);
-            newCompletedStages.add("new");
             const newConfig = { ...config.sqlConfig };
             if (clientPk !== undefined) {
-                // Store the boolean OR the function directly into the config
                 newConfig.isClientPk = clientPk;
             }
             let clientAndServerSchema;
             if (clientPk) {
-                // Always union for clientPk fields
                 clientAndServerSchema = z.union([config.sqlZod, finalSchema]);
             }
-            else if (schemaOrModifier) {
-                // Schema provided without clientPk — use as-is
-                clientAndServerSchema = finalSchema;
+            else if (schemaOrModifier !== undefined) {
+                if (isDirectShortcut) {
+                    clientAndServerSchema = finalSchema;
+                }
+                else {
+                    clientAndServerSchema = finalSchema;
+                }
             }
             else {
-                // No schema provided — union with SQL type
-                clientAndServerSchema = z.union([config.sqlZod, finalSchema]);
+                if (config.sqlZod instanceof z.ZodUndefined) {
+                    clientAndServerSchema = finalSchema;
+                }
+                else {
+                    clientAndServerSchema = z.union([config.sqlZod, finalSchema]);
+                }
             }
             return createBuilder({
                 ...config,
-                stage: "new",
+                stage: "client",
                 sqlConfig: newConfig,
-                newZod: finalSchema,
                 initialValue: actualValue,
                 clientZod: clientAndServerSchema,
                 validationZod: clientAndServerSchema,
                 completedStages: newCompletedStages,
             });
         },
-        reference: (fieldGetter) => {
-            return createBuilder({
-                ...config,
-                sqlConfig: {
-                    ...config.sqlConfig,
-                    reference: fieldGetter,
-                },
-            });
-        },
-        client: (assert) => {
-            if (completedStages.has("client")) {
-                throw new Error("client() can only be called once in the chain");
-            }
-            if (completedStages.has("server")) {
-                throw new Error("client() must be called before validation()");
-            }
-            const newCompletedStages = new Set(completedStages);
-            newCompletedStages.add("client");
-            if (config.stage === "relation") {
-                return createBuilder({
-                    ...config,
-                    stage: "client",
-                    completedStages: newCompletedStages,
-                    clientTransform: (baseSchema) => {
-                        if (isFunction(assert)) {
-                            return assert({
-                                sql: baseSchema,
-                                initialState: config.newZod,
-                            });
-                        }
-                        return assert;
-                    },
-                });
-            }
-            const clientSchema = isFunction(assert)
-                ? assert({ sql: config.sqlZod, initialState: config.newZod })
-                : assert;
-            return createBuilder({
-                ...config,
-                stage: "client",
-                clientZod: clientSchema,
-                validationZod: clientSchema,
-                completedStages: newCompletedStages,
-            });
-        },
         server: (assert) => {
             if (completedStages.has("server")) {
-                throw new Error("validation() can only be called once in the chain");
+                throw new Error("server() can only be called once in the chain");
             }
             const serverSchema = isFunction(assert)
                 ? assert({
                     sql: config.sqlZod,
-                    initialState: config.newZod,
                     client: config.clientZod,
                 })
                 : assert;
@@ -263,7 +283,7 @@ function createBuilder(config) {
         },
         transform: (transforms) => {
             if (!completedStages.has("server") && !completedStages.has("client")) {
-                throw new Error("transform() requires at least client() or validation() to be called first");
+                throw new Error("transform() requires at least client() or server() to be called first");
             }
             return {
                 config: {
@@ -280,7 +300,6 @@ function createBuilder(config) {
 }
 export const SchemaWrapperBrand = Symbol("SchemaWrapper");
 export function schema(schema) {
-    // Create the enriched schema with all fields
     const enrichedSchema = {};
     for (const key in schema) {
         if (Object.prototype.hasOwnProperty.call(schema, key)) {
@@ -298,6 +317,7 @@ export function schema(schema) {
     }
     enrichedSchema[SchemaWrapperBrand] = true;
     enrichedSchema.__primaryKeySQL = undefined;
+    enrichedSchema.__derives = undefined;
     enrichedSchema.primaryKeySQL = function (definer) {
         const pkFieldsOnly = {};
         for (const key in schema) {
@@ -311,6 +331,10 @@ export function schema(schema) {
         enrichedSchema.__primaryKeySQL = definer(pkFieldsOnly);
         return enrichedSchema;
     };
+    enrichedSchema.derive = function (derivers) {
+        enrichedSchema.__derives = derivers;
+        return enrichedSchema;
+    };
     return enrichedSchema;
 }
 function inferDefaultFromZod(zodType, sqlConfig) {
@@ -323,10 +347,6 @@ function inferDefaultFromZod(zodType, sqlConfig) {
         if ("default" in sqlConfig && sqlConfig.default !== undefined) {
             return sqlConfig.default;
         }
-        if (typeof sqlConfig.type === "string" &&
-            ["hasMany", "hasOne", "belongsTo", "manyToMany"].includes(sqlConfig.type)) {
-            // ...
-        }
         const sqlTypeConfig = sqlConfig;
         if (sqlTypeConfig.type && !sqlTypeConfig.nullable) {
             switch (sqlTypeConfig.type) {
@@ -373,13 +393,16 @@ export function createSchema(schema, relations) {
     const fieldTransforms = {};
     const clientToDbKeys = {};
     const dbToClientKeys = {};
+    const sqlOnlyDbKeys = new Set();
     const fullSchema = { ...schema, ...(relations || {}) };
     let pkKeys = [];
     let clientPkKeys = [];
+    const derives = schema.__derives;
     for (const key in fullSchema) {
         const value = fullSchema[key];
         if (key === "_tableName" ||
             key.startsWith("__") ||
+            key === "derive" ||
             key === String(SchemaWrapperBrand) ||
             key === "primaryKeySQL" ||
             typeof value === "function")
@@ -390,19 +413,29 @@ export function createSchema(schema, relations) {
             if (targetField && targetField.config) {
                 const config = targetField.config;
                 const dbFieldName = config.sql?.field || key;
-                clientToDbKeys[key] = dbFieldName;
-                dbToClientKeys[dbFieldName] = key;
                 sqlFields[dbFieldName] = config.zodSqlSchema;
-                clientFields[key] = config.zodClientSchema;
-                serverFields[key] = config.zodValidationSchema;
-                const initialValueOrFn = config.initialValue;
-                defaultGenerators[key] = initialValueOrFn;
-                let rawDefault = isFunction(initialValueOrFn)
-                    ? initialValueOrFn({ uuid })
-                    : initialValueOrFn;
-                defaultValues[key] = rawDefault;
-                if (config.transforms) {
-                    fieldTransforms[key] = config.transforms;
+                if (config.sql?.sqlOnly) {
+                    sqlOnlyDbKeys.add(dbFieldName);
+                }
+                else {
+                    clientToDbKeys[key] = dbFieldName;
+                    dbToClientKeys[dbFieldName] = key;
+                    clientFields[key] = config.zodClientSchema;
+                    serverFields[key] = config.zodValidationSchema;
+                    const initialValueOrFn = config.initialValue;
+                    defaultGenerators[key] = initialValueOrFn;
+                    let rawDefault = isFunction(initialValueOrFn)
+                        ? initialValueOrFn({ uuid })
+                        : initialValueOrFn;
+                    if (config.transforms?.toClient && rawDefault !== undefined) {
+                        defaultValues[key] = config.transforms.toClient(rawDefault);
+                    }
+                    else {
+                        defaultValues[key] = rawDefault;
+                    }
+                    if (config.transforms) {
+                        fieldTransforms[key] = config.transforms;
+                    }
                 }
             }
             continue;
@@ -419,11 +452,34 @@ export function createSchema(schema, relations) {
                 ["hasMany", "hasOne", "belongsTo", "manyToMany"].includes(sqlConfig.type)) {
                 continue;
             }
-            else {
-                const dbFieldName = sqlConfig?.field || key;
-                clientToDbKeys[key] = dbFieldName;
-                dbToClientKeys[dbFieldName] = key;
+            else if (sqlConfig) {
+                const dbFieldName = sqlConfig.field || key;
                 sqlFields[dbFieldName] = config.zodSqlSchema;
+                if (sqlConfig.sqlOnly) {
+                    sqlOnlyDbKeys.add(dbFieldName);
+                }
+                else {
+                    clientToDbKeys[key] = dbFieldName;
+                    dbToClientKeys[dbFieldName] = key;
+                    clientFields[key] = config.zodClientSchema;
+                    serverFields[key] = config.zodValidationSchema;
+                    if (config.transforms) {
+                        fieldTransforms[key] = config.transforms;
+                    }
+                    const initialValueOrFn = config.initialValue;
+                    defaultGenerators[key] = initialValueOrFn;
+                    let rawDefault = isFunction(initialValueOrFn)
+                        ? initialValueOrFn({ uuid })
+                        : initialValueOrFn;
+                    if (config.transforms?.toClient && rawDefault !== undefined) {
+                        defaultValues[key] = config.transforms.toClient(rawDefault);
+                    }
+                    else {
+                        defaultValues[key] = rawDefault;
+                    }
+                }
+            }
+            else {
                 clientFields[key] = config.zodClientSchema;
                 serverFields[key] = config.zodValidationSchema;
                 if (config.transforms) {
@@ -443,7 +499,6 @@ export function createSchema(schema, relations) {
             }
         }
     }
-    // --- NEW: SMART CHECKER BUILDER ---
     let isClientRecord = () => false;
     if (clientPkKeys.length > 0) {
         const checkers = [];
@@ -453,21 +508,16 @@ export function createSchema(schema, relations) {
             const dbKey = sqlConfig?.field || key;
             const isClientPkVal = sqlConfig?.isClientPk;
             if (typeof isClientPkVal === "function") {
-                // Explicit checker provided directly in the field!
                 checkers.push({ clientKey: key, dbKey, check: isClientPkVal });
             }
             else {
-                // Fallback auto-detection: If they just passed `true`
                 const initialValueOrFn = field?.config?.initialValue;
                 let sampleValue = initialValueOrFn;
-                // Safely execute the function once to figure out its return type!
                 if (isFunction(initialValueOrFn)) {
                     try {
                         sampleValue = initialValueOrFn({ uuid });
                     }
-                    catch (e) {
-                        // Ignore if the factory fails with a dummy payload
-                    }
+                    catch (e) { }
                 }
                 if (sqlConfig?.type === "int" && typeof sampleValue === "string") {
                     checkers.push({
@@ -483,7 +533,6 @@ export function createSchema(schema, relations) {
                 if (!record || typeof record !== "object")
                     return false;
                 return checkers.some(({ clientKey, dbKey, check }) => {
-                    // Look at both the client shape key AND the db shape key safely
                     const val = record[clientKey] !== undefined ? record[clientKey] : record[dbKey];
                     return check(val);
                 });
@@ -501,6 +550,11 @@ export function createSchema(schema, relations) {
                 ? fieldTransforms[key].toClient(rawValue)
                 : rawValue;
         }
+        if (derives) {
+            for (const key in derives) {
+                freshDefaults[key] = derives[key](freshDefaults);
+            }
+        }
         return freshDefaults;
     };
     const toClient = (dbObject) => {
@@ -508,12 +562,19 @@ export function createSchema(schema, relations) {
         for (const dbKey in dbObject) {
             if (dbObject[dbKey] === undefined)
                 continue;
+            if (sqlOnlyDbKeys.has(dbKey))
+                continue;
             const clientKey = dbToClientKeys[dbKey] || dbKey;
             const transform = fieldTransforms[clientKey]?.toClient;
             clientObject[clientKey] = transform
                 ? transform(dbObject[dbKey])
                 : dbObject[dbKey];
         }
+        if (derives) {
+            for (const key in derives) {
+                clientObject[key] = derives[key](clientObject);
+            }
+        }
         return clientObject;
     };
     const toDb = (clientObject) => {
@@ -615,31 +676,8 @@ function createViewObject(initialRegistryKey, selection, registry, tableNameToRe
         supportsReconciliation: allTablesSupportsReconciliation,
     };
 }
-export function createSchemaBox(schemas, resolver) {
-    const schemaProxy = new Proxy({}, {
-        get(target, tableName) {
-            const schema = schemas[tableName];
-            if (!schema)
-                return undefined;
-            return new Proxy({}, {
-                get(target, fieldName) {
-                    const field = schema[fieldName];
-                    if (field && typeof field === "object") {
-                        return {
-                            ...field,
-                            __meta: {
-                                _key: fieldName,
-                                _fieldType: field,
-                            },
-                            __parentTableType: schema,
-                        };
-                    }
-                    return field;
-                },
-            });
-        },
-    });
-    const resolutionConfig = resolver(schemaProxy);
+export function createSchemaBox(schemas, resolutions) {
+    const resolutionConfig = resolutions;
     const resolvedSchemas = schemas;
     for (const tableName in schemas) {
         for (const fieldName in schemas[tableName]) {
@@ -694,7 +732,6 @@ export function createSchemaBox(schemas, resolver) {
                         defaultConfig: field.defaultConfig,
                     },
                     sqlZod: zodSchema,
-                    newZod: zodSchema,
                     initialValue,
                     clientZod: zodSchema,
                     validationZod: zodSchema,
@@ -709,6 +746,16 @@ export function createSchemaBox(schemas, resolver) {
         finalRegistry[tableName] = {
             rawSchema: resolvedSchemas[tableName],
             zodSchemas: zodSchemas,
+            transforms: {
+                toClient: zodSchemas.toClient,
+                toDb: zodSchemas.toDb,
+                parseForDb: zodSchemas.parseForDb,
+                parseFromDb: zodSchemas.parseFromDb,
+            },
+            pk: zodSchemas.pk,
+            clientPk: zodSchemas.clientPk,
+            isClientRecord: zodSchemas.isClientRecord,
+            generateDefaults: zodSchemas.generateDefaults,
         };
     }
     const createNavProxy = (currentTable, registry) => {
@@ -746,17 +793,17 @@ export function createSchemaBox(schemas, resolver) {
                 server: entry.zodSchemas.serverSchema,
             },
             transforms: {
-                toClient: entry.zodSchemas.toClient,
-                toDb: entry.zodSchemas.toDb,
+                toClient: entry.transforms.toClient,
+                toDb: entry.transforms.toDb,
+                parseForDb: entry.transforms.parseForDb,
+                parseFromDb: entry.transforms.parseFromDb,
             },
-            parseForDb: entry.zodSchemas.parseForDb,
-            parseFromDb: entry.zodSchemas.parseFromDb,
-            defaults: entry.zodSchemas.defaultValues,
+            defaults: entry.generateDefaults(),
             stateType: entry.zodSchemas.stateType,
-            generateDefaults: entry.zodSchemas.generateDefaults,
-            pk: entry.zodSchemas.pk,
-            clientPk: entry.zodSchemas.clientPk,
-            isClientRecord: entry.zodSchemas.isClientRecord,
+            generateDefaults: entry.generateDefaults,
+            pk: entry.pk,
+            clientPk: entry.clientPk,
+            isClientRecord: entry.isClientRecord,
             nav: createNavProxy(tableName, finalRegistry),
             createView: (selection) => {
                 const view = createViewObject(tableName, selection, finalRegistry, tableNameToRegistryKeyMap);
@@ -767,7 +814,7 @@ export function createSchemaBox(schemas, resolver) {
                     if (Array.isArray(dbData))
                         return dbData.map((item) => deepToClient(item, currentSelection, currentKey));
                     const regEntry = finalRegistry[currentKey];
-                    const baseMapped = regEntry.zodSchemas.toClient(dbData);
+                    const baseMapped = { ...regEntry.transforms.toClient(dbData) };
                     if (typeof currentSelection === "object") {
                         for (const relKey in currentSelection) {
                             if (currentSelection[relKey] &&
@@ -784,16 +831,20 @@ export function createSchemaBox(schemas, resolver) {
                             }
                         }
                     }
+                    if (regEntry.rawSchema.__derives) {
+                        for (const key in regEntry.rawSchema.__derives) {
+                            baseMapped[key] = regEntry.rawSchema.__derives[key](baseMapped);
+                        }
+                    }
                     return baseMapped;
                 };
-                // --- NEW: Implement recursive toDb ---
                 const deepToDb = (clientData, currentSelection, currentKey) => {
                     if (!clientData)
                         return clientData;
                     if (Array.isArray(clientData))
                         return clientData.map((item) => deepToDb(item, currentSelection, currentKey));
                     const regEntry = finalRegistry[currentKey];
-                    const baseMapped = regEntry.zodSchemas.toDb(clientData);
+                    const baseMapped = regEntry.transforms.toDb(clientData);
                     if (typeof currentSelection === "object") {
                         for (const relKey in currentSelection) {
                             if (currentSelection[relKey] &&
@@ -813,7 +864,6 @@ export function createSchemaBox(schemas, resolver) {
                     return baseMapped;
                 };
                 const viewToClient = (dbData) => deepToClient(dbData, selection, tableName);
-                // --- NEW: View To Db ---
                 const viewToDb = (clientData) => deepToDb(clientData, selection, tableName);
                 return {
                     definition: entry.rawSchema,
@@ -825,16 +875,13 @@ export function createSchemaBox(schemas, resolver) {
                     },
                     transforms: {
                         toClient: viewToClient,
-                        toDb: viewToDb, // <--- UPDATED: now uses the recursive function
-                    },
-                    // --- UPDATED: uses view.server.parse to retain relation arrays/objects instead of stripping them
-                    parseForDb: (appData) => {
-                        const validData = view.server.parse(appData);
-                        return viewToDb(validData);
-                    },
-                    parseFromDb: (dbData) => {
-                        const mapped = viewToClient(dbData);
-                        return view.client.parse(mapped);
+                        toDb: viewToDb,
+                        parseForDb: (appData) => {
+                            return viewToDb(appData);
+                        },
+                        parseFromDb: (dbData) => {
+                            return viewToClient(dbData);
+                        },
                     },
                     defaults: defaults,
                     pk: entry.zodSchemas.pk,
@@ -863,7 +910,7 @@ function computeViewDefaults(currentRegistryKey, selection, registry, tableNameT
         return {};
     }
     const rawSchema = entry.rawSchema;
-    const baseDefaults = { ...entry.zodSchemas.defaultValues };
+    const baseDefaults = entry.generateDefaults();
     if (selection === true || typeof selection !== "object") {
         return baseDefaults;
     }

package/package.json

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