cogsbox-shape 0.5.110 → 0.5.112

package/README.md

@@ -121,9 +121,11 @@ const userSchema = schema({
 });
 ```
 
-## Relationships with Schema Box Registry
+## Relationships and Views
 
-Define relationships between schemas using the Schema Box Registry pattern:
+Define relationships between schemas and create specific data views using the `createSchemaBox`.
+
+### 1. Define Schemas with Placeholders
 
 ```typescript
 import { s, schema, createSchemaBox } from "cogsbox-shape";
@@ -133,31 +135,71 @@ const users = schema({
   _tableName: "users",
   id: s.sql({ type: "int", pk: true }),
   name: s.sql({ type: "varchar" }),
-  posts: s.hasMany(), // Placeholder for relationship
+  posts: s.hasMany(), // Placeholder for a one-to-many relationship
 });
 
 const posts = schema({
   _tableName: "posts",
   id: s.sql({ type: "int", pk: true }),
   title: s.sql({ type: "varchar" }),
-  authorId: s.reference(() => users.id), // Reference to user
+  authorId: s.reference(() => users.id), // Foreign key reference
 });
+```
+
+### 2. Create the Registry (The "Box")
 
-// Create registry and resolve relationships
-const schemas = createSchemaBox({ users, posts }, (s) => ({
+The `createSchemaBox` function processes your raw schemas, resolves the relationships, and gives you a powerful, type-safe API for accessing them.
+
+```typescript
+const box = createSchemaBox({ users, posts }, (s) => ({
   users: {
+    // Resolve the 'posts' relation on the 'users' schema
     posts: { fromKey: "id", toKey: s.posts.authorId },
   },
 }));
+```
 
-// Use the schemas
-const { zodSchemas } = schemas.users;
-const { clientSchema, defaultValues, toClient, toDb } = zodSchemas;
+### 3. Access Base Schemas and Defaults
+
+Once the box is created, you can access the base schemas (without relations) and their default values.
+
+```typescript
+// Access the processed schemas for the 'users' table
+const userSchemas = box.users.schemas;
+const userDefaults = box.users.defaults;
 
 // Type-safe operations
-const newUser = defaultValues; // Fully typed with defaults
-const dbUser = toDb(clientData); // Transform for database
-const apiUser = toClient(dbData); // Transform for API
+const newUser = userDefaults; // { id: 0, name: '' }
+
+// The base schema does NOT include the 'posts' relation
+type UserClient = z.infer<typeof userSchemas.client>; // { id: number; name: string; }
+```
+
+### 4. Create Views to Include Relations
+
+The real power is in creating views to select exactly which relationships to include for a given operation.
+
+```typescript
+// Create a view that includes the 'posts' for a user
+const userWithPostsView = box.users.createView({
+  posts: true, // Select the 'posts' relation
+});
+
+// The type of this view now includes the nested posts
+type UserWithPosts = z.infer<typeof userWithPostsView.client>;
+// {
+//   id: number;
+//   name: string;
+//   posts: {
+//     id: number;
+//     title: string;
+//     authorId: number;
+//   }[];
+// }
+
+// You can also get default values for the view
+const newUserWithPosts = userWithPostsView.defaults;
+// { id: 0, name: '', posts: [] }
 ```
 
 ## Real-World Example
@@ -179,10 +221,7 @@ const users = schema({
 
   metadata: s
     .sql({ type: "text" })
-    .initialState(() => ({
-      preferences: { theme: "light", notifications: true },
-    }))
-    .client(() =>
+    .client(
       z.object({
         preferences: z.object({
           theme: z.enum(["light", "dark"]),
@@ -195,7 +234,7 @@ const users = schema({
       toDb: (obj) => JSON.stringify(obj),
     }),
 
-  posts: s.hasMany({ defaultCount: 0 }),
+  posts: s.hasMany({ defaultCount: 0 }), // Default to an empty array
 });
 
 const posts = schema({
@@ -212,65 +251,75 @@ const posts = schema({
   authorId: s.reference(() => users.id),
 });
 
-const schemas = createSchemaBox({ users, posts }, (s) => ({
+const box = createSchemaBox({ users, posts }, (s) => ({
   users: {
     posts: { fromKey: "id", toKey: s.posts.authorId },
   },
 }));
 
-// Use in your app
-const userSchemas = schemas.users.zodSchemas;
-type User = z.infer<typeof userSchemas.clientSchema>;
+// Use a view for our API response
+const userApiView = box.users.createView({ posts: true });
+
+// Use the schemas from the view
+const { clientSchema, validationSchema, defaults, toClient, toDb } =
+  userApiView;
+type UserApiResponse = z.infer<typeof clientSchema>;
 // {
 //   id: string | number;
 //   email: string;
-//   metadata: { preferences: { theme: "light" | "dark"; notifications: boolean } };
-//   posts: Array<Post>;
+//   metadata: { preferences: { theme: 'light' | 'dark'; notifications: boolean; } };
+//   posts: { id: number; title: string; published: boolean; authorId: number | string; }[];
 // }
 
-// Create new user with defaults
-const newUser = userSchemas.defaultValues;
+// Create a new user with view-aware defaults
+const newUser = defaults;
+// newUser.posts is now guaranteed to be an empty array.
 
-// Validate user input
-const validated = userSchemas.validationSchema.parse(userInput);
+// Validate user input against the view's validation schema
+const validated = validationSchema.parse(userInput);
 
 // Transform for database
-const dbUser = userSchemas.toDb(validated);
+const dbUser = toDb(validated);
 
 // Transform for API response
-const apiUser = userSchemas.toClient(dbUser);
+const apiUser = toClient(dbUser);
 ```
 
 ## Why This Approach?
 
-1. **Type Safety**: Full TypeScript support with inferred types at every layer
-2. **Single Source of Truth**: Define your schema once, use it everywhere
-3. **Transformation Co-location**: Keep data transformations next to field definitions
-4. **Progressive Enhancement**: Start simple, add complexity as needed
-5. **Framework Agnostic**: Works with any TypeScript project
+1.  **Type Safety**: Full TypeScript support with inferred types at every layer.
+2.  **Single Source of Truth**: Define your schema once, use it everywhere.
+3.  **Explicit Data Loading**: Views encourage explicitly defining the data shape you need, preventing over-fetching.
+4.  **Transformation Co-location**: Keep data transformations next to field definitions.
+5.  **Progressive Enhancement**: Start simple, add complexity as needed.
+6.  **Framework Agnostic**: Works with any TypeScript project.
 
 ## API Reference
 
 ### Schema Definition
 
-- `s.sql(config)`: Define SQL column type
-- `.initialState(value)`: Set default value for new records
-- `.client(schema)`: Define client-side schema
-- `.validation(schema)`: Add validation rules
-- `.transform(transforms)`: Define bidirectional transformations
+- `s.sql(config)`: Define SQL column type.
+- `.initialState(value)`: Set default value for new records.
+- `.client(schema)`: Define client-side schema.
+- `.validation(schema)`: Add validation rules.
+- `.transform(transforms)`: Define bidirectional transformations.
 
 ### Relationships
 
-- `s.reference(getter)`: Create a foreign key reference
-- `s.hasMany(config)`: Define one-to-many relationship
-- `s.hasOne()`: Define one-to-one relationship
-- `s.manyToMany(config)`: Define many-to-many relationship
+- `s.reference(getter)`: Create a foreign key reference.
+- `s.hasMany(config)`: Define one-to-many relationship placeholder.
+- `s.hasOne()`: Define one-to-one relationship placeholder.
+- `s.manyToMany(config)`: Define many-to-many relationship placeholder.
 
 ### Schema Processing
 
-- `schema(definition)`: Create a schema definition
-- `createSchemaBox(schemas, resolver)`: Create and resolve schema relationships
-- `createSchema(schema, relations?)`: Generate Zod schemas (legacy API)
+- `schema(definition)`: Create a schema definition.
+- `createSchemaBox(schemas, resolver)`: The main function to create and resolve a schema registry.
+- From the box entry (e.g., `box.users`):
+  - `.schemas`: Access base Zod schemas (sql, client, validation).
+  - `.defaults`: Access base default values.
+  - `.transforms`: Access `toClient` and `toDb` functions for the base schema.
+  - `.createView(selection)`: Creates a new set of schemas and transforms including the selected relations.
 
 ## License
 

package/dist/schema.d.ts

@@ -306,6 +306,25 @@ type RegistryShape = Record<string, {
         toDb: (clientObject: any) => any;
     };
 }>;
+type DeriveViewDefaults<TTableName extends keyof TRegistry, TSelection, TRegistry extends RegistryShape, Depth extends any[] = []> = Depth["length"] extends 10 ? any : // 1. Start with the base defaults for the table (id, name, etc.)
+DeriveDefaults<TRegistry[TTableName]["rawSchema"]> & (TSelection extends Record<string, any> ? {
+    -readonly [K in keyof TSelection & keyof TRegistry[TTableName]["rawSchema"]]?: TRegistry[TTableName]["rawSchema"][K] extends {
+        config: {
+            sql: {
+                type: infer RelType;
+                schema: () => infer S;
+            };
+        };
+    } ? S extends {
+        _tableName: infer Target;
+    } ? Target extends keyof TRegistry ? RelType extends "hasMany" | "manyToMany" ? DeriveViewDefaults<Target, TSelection[K], TRegistry, [
+        ...Depth,
+        1
+    ]>[] : DeriveViewDefaults<Target, TSelection[K], TRegistry, [
+        ...Depth,
+        1
+    ]> | null | undefined : never : never : never;
+} : {});
 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]: {
         definition: Resolved[K]["rawSchema"];
@@ -325,7 +344,7 @@ type CreateSchemaBoxReturn<S extends Record<string, SchemaWithPlaceholders>, R e
             sql: Resolved[K]["zodSchemas"]["sqlSchema"];
             client: z.ZodObject<BuildZodShape<K, TSelection, "clientSchema", Resolved>>;
             validation: z.ZodObject<BuildZodShape<K, TSelection, "validationSchema", Resolved>>;
-            defaults: any;
+            defaults: Prettify<DeriveViewDefaults<K & string, TSelection, Resolved>>;
         };
     };
 };

package/dist/schema.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z, ZodType } from "zod";
 import { ca } from "zod/v4/locales";
 export const isFunction = (fn) => typeof fn === "function";
 // Function to create a properly typed current timestamp config
@@ -301,10 +301,8 @@ function inferDefaultFromZod(zodType, sqlConfig) {
             if (sqlConfig.default === "CURRENT_TIMESTAMP") {
                 return undefined;
             }
-            // Otherwise, use the provided SQL default.
             return sqlConfig.default;
         }
-        // --- PRESERVED LOGIC: Handle relation types (NO CHANGES HERE) ---
         if (typeof sqlConfig.type === "string" &&
             ["hasMany", "hasOne", "belongsTo", "manyToMany"].includes(sqlConfig.type)) {
             const relationConfig = sqlConfig;
@@ -317,7 +315,6 @@ function inferDefaultFromZod(zodType, sqlConfig) {
                 return {};
             }
         }
-        // --- PRESERVED LOGIC: Handle basic SQL types as a fallback (NO CHANGES HERE) ---
         const sqlTypeConfig = sqlConfig;
         if (sqlTypeConfig.type && !sqlTypeConfig.nullable) {
             switch (sqlTypeConfig.type) {
@@ -339,19 +336,16 @@ function inferDefaultFromZod(zodType, sqlConfig) {
             return null;
         }
     }
-    // --- PRESERVED LOGIC: Fall back to Zod-based inference ---
-    if (zodType instanceof z.ZodOptional) {
-        return undefined;
-    }
-    if (zodType instanceof z.ZodDefault && zodType._def?.defaultValue) {
-        return typeof zodType._def.defaultValue === "function"
-            ? zodType._def.defaultValue()
-            : zodType._def.defaultValue;
+    if ("_def" in zodType && "defaultValue" in zodType._def) {
+        const def = zodType._def;
+        const val = def.defaultValue;
+        if (val !== undefined) {
+            return typeof val === "function" ? val() : val;
+        }
     }
     if (zodType instanceof z.ZodString) {
         return "";
     }
-    // Return undefined if no other default can be determined.
     return undefined;
 }
 export function createMixedValidationSchema(schema, clientSchema, dbSchema) {
@@ -528,30 +522,26 @@ function createViewObject(tableName, selection, registry) {
         const registryEntry = registry[currentTable];
         const rawSchema = registryEntry.rawSchema;
         const baseSchema = registryEntry.zodSchemas[`${schemaType}Schema`];
-        // Get all relation keys
-        const relationsToOmit = {};
-        for (const key in rawSchema) {
-            if (rawSchema[key]?.config?.sql?.schema) {
-                relationsToOmit[key] = true;
-            }
-        }
-        // Start with primitive fields only
-        const schemaWithPrimitives = baseSchema.omit(relationsToOmit);
-        // If selection is just `true`, return primitives only (no nested relations)
+        // --- START OF THE FIX ---
+        // 1. Get the shape of the base schema (e.g., { id: z.ZodNumber, name: z.ZodString })
+        // The base schema correctly contains only primitive/referenced fields.
+        const primitiveShape = baseSchema.shape;
+        // 2. If the selection is just `true`, we don't need to add any relations.
         if (subSelection === true) {
-            return schemaWithPrimitives;
+            return z.object(primitiveShape);
         }
-        // Otherwise, add selected relations
+        // 3. Build a new shape object for the selected relations.
         const selectedRelationShapes = {};
         if (typeof subSelection === "object") {
             for (const key in subSelection) {
-                if (subSelection[key] && relationsToOmit[key]) {
+                // We only care about keys that are actual relations in the raw schema.
+                if (subSelection[key] && rawSchema[key]?.config?.sql?.schema) {
                     const relationConfig = rawSchema[key].config.sql;
                     const targetTable = relationConfig.schema()._tableName;
-                    // Recursively build the sub-schema
+                    // Recursively build the sub-schema for the relation.
                     const subSchema = buildView(targetTable, schemaType, subSelection[key]);
-                    if (relationConfig.type === "hasMany" ||
-                        relationConfig.type === "manyToMany") {
+                    // Wrap it in an array or optional as needed.
+                    if (["hasMany", "manyToMany"].includes(relationConfig.type)) {
                         selectedRelationShapes[key] = z.array(subSchema);
                     }
                     else {
@@ -560,14 +550,18 @@ function createViewObject(tableName, selection, registry) {
                 }
             }
         }
-        return schemaWithPrimitives.extend(selectedRelationShapes);
+        // 4. Combine the primitive shape and the new relation shapes into one final shape.
+        const finalShape = { ...primitiveShape, ...selectedRelationShapes };
+        // 5. Return a brand new, clean Zod object from the final shape.
+        return z.object(finalShape);
+        // --- END OF THE FIX ---
     }
-    // The main function builds the final object with all three schemas.
+    // The main function builds the final object with both schemas.
     const sourceRegistryEntry = registry[tableName];
     return {
-        sql: sourceRegistryEntry.zodSchemas.sqlSchema, // Changed from sqlSchema
-        client: buildView(tableName, "client", selection), // Changed from clientSchema
-        validation: buildView(tableName, "validation", selection), // Changed from validationSchema
+        sql: sourceRegistryEntry.zodSchemas.sqlSchema,
+        client: buildView(tableName, "client", selection),
+        validation: buildView(tableName, "validation", selection),
     };
 }
 export function createSchemaBox(schemas, resolver) {

package/package.json

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