cogsbox-shape 0.5.69 → 0.5.71

package/README.md

@@ -1,184 +1,234 @@
-# Unified Schema
+# cogsbox-shape
 
-> ⚠️ **Warning**: This package is currently a work in progress and not ready for production use. The API is unstable and subject to breaking changes. Please do not use in production environments.
+> [!CAUTION]
+> **This library is under active development and the API is rapidly changing. Do not use in production.**
+>
+> Breaking changes are expected between any release. The library is currently in an experimental phase as we work towards a stable v1.0 release.
 
----
-
-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.
-
-## Features
-
-- Single source of truth for database, server, and client types
-- Type-safe schema definitions with TypeScript
-- Built-in Zod validation
-- Automatic type transformations between client and database
-- Relationship handling (hasMany, hasOne, belongsTo)
-- Schema serialization
-- Default value generation
+A TypeScript-first schema declaration and validation library for full-stack applications. Define your database schema once and get type-safe schemas for your database, client, and validation layers with automatic transformations.
 
 ## Installation
 
 ```bash
 npm install cogsbox-shape
+# or
+yarn add cogsbox-shape
+# or
+pnpm add cogsbox-shape
 ```
 
-## Basic Usage
+## The Problem
 
-```typescript
-import { shape, hasMany, createSchema } from "cogsbox-shape";
+In full-stack applications, data flows through multiple layers:
 
-const productSchema = {
-  _tableName: "products",
-  id: shape.sql({ type: "int", pk: true }),
-  sku: shape
-    .sql({ type: "varchar", length: 50 })
-    .initialState(
-      z.string(),
-      () => "PRD-" + Math.random().toString(36).slice(2)
-    )
-    .validation(({ sql }) => sql.min(5).max(50)),
-  price: shape
-    .sql({ type: "int" })
-    .client(({ sql }) => z.number().multipleOf(0.01))
-    .transform({
-      toClient: (dbValue) => dbValue / 100,
-      toDb: (clientValue) => Math.round(clientValue * 100),
-    }),
-  inStock: shape
-    .sql({ type: "boolean" })
-    .client(({ sql }) => z.boolean())
-    .initialState(z.boolean(), () => true),
-  categories: hasMany({
-    fromKey: "id",
-    toKey: () => categorySchema.productId,
-    schema: () => categorySchema,
-  }),
-};
+- **Database** stores data in SQL types (integers, varchars, etc.)
+- **Server** needs to transform data for clients (e.g., convert cents to dollars)
+- **Client** expects data in specific formats (e.g., UUIDs as strings, not numbers)
+- **Forms** need validation rules and default values
+
+Traditional approaches require defining these transformations in multiple places, leading to type mismatches and runtime errors.
+
+## The Solution: The Shape Flow
+
+cogsbox-shape introduces a unified flow that mirrors how data moves through your application:
 
-const { sqlSchema, clientSchema, validationSchema, defaultValues } =
-  createSchema(productSchema);
 ```
+SQL → Initial State → Client → Validation
+```
+
+This flow ensures type safety at every step while giving you control over transformations.
 
-## Advanced Features
+## Core Concept: The Shape Flow
 
-### Type Transformations
+### 1. SQL - Define Your Database Schema
 
-Transform data between client and database representations:
+Start with your database reality:
 
 ```typescript
-const orderSchema = {
-  _tableName: "orders",
-  id: shape
-    .sql({ type: "int", pk: true })
-    .initialState(z.string().uuid(), () => crypto.randomUUID())
+const userSchema = schema({
+  _tableName: "users",
+  id: s.int({ pk: true }), // In DB: integer auto-increment
+  email: s.varchar({ length: 255 }),
+  createdAt: s.datetime({ default: "CURRENT_TIMESTAMP" }),
+});
+```
+
+### 2. Initial State - Define Creation Defaults
+
+When creating new records, you often need different types than what's stored in the database. Initial state serves two purposes: defining default values AND adding additional types to the client schema.
+
+```typescript
+const userSchema = schema({
+  _tableName: "users",
+  id: s
+    .int({ pk: true })
+    .initialState(z.string().uuid(), () => crypto.randomUUID()),
+  // DB stores integers, but client can work with UUID strings for new records
+  // This automatically creates a union type: number | string on the client
+});
+```
+
+### 3. Client - Define Client Representation
+
+Transform how data appears to clients:
+
+```typescript
+const productSchema = schema({
+  _tableName: "products",
+  id: s
+    .int({ pk: true })
+    .initialState(z.string(), () => `tmp_${Date.now()}`)
     .client(({ sql, initialState }) => z.union([sql, initialState])),
-  status: shape
-    .sql({ type: "varchar", length: 20 })
-    .client(({ sql }) =>
-      z.enum(["pending", "processing", "shipped", "delivered"])
-    )
-    .validation(({ sql }) =>
-      sql.refine((val) =>
-        ["pending", "processing", "shipped", "delivered"].includes(val)
-      )
-    ),
-  metadata: shape
-    .sql({ type: "text" })
-    .client(({ sql }) => z.record(z.unknown()))
-    .transform({
-      toClient: (value) => JSON.parse(value),
-      toDb: (value) => JSON.stringify(value),
-    }),
-  createdAt: shape
-    .sql({ type: "datetime" })
-    .client(({ sql }) => z.string().datetime())
+  // Client can receive either the integer (from DB) or string (when creating)
+
+  price: s
+    .int() // Stored as cents in DB
+    .client(() => z.number().multipleOf(0.01)) // But dollars on client
     .transform({
-      toClient: (date) => date.toISOString(),
-      toDb: (isoString) => new Date(isoString),
+      toClient: (cents) => cents / 100,
+      toDb: (dollars) => Math.round(dollars * 100),
     }),
-};
+});
 ```
 
-### Relationships
+### 4. Validation - Define Business Rules
 
-Define relationships between schemas:
+Add validation that runs before data enters your system:
 
 ```typescript
-const customerSchema = {
-  _tableName: "customers",
-  id: shape.sql({ type: "int", pk: true }),
-  name: shape.sql({ type: "varchar", length: 100 }),
-  orders: hasMany({
-    fromKey: "id",
-    toKey: () => orderSchema.customerId,
-    schema: () => orderSchema,
-  }),
-  primaryAddress: hasOne({
-    fromKey: "id",
-    toKey: () => addressSchema.customerId,
-    schema: () => addressSchema,
-  }),
-  company: belongsTo({
-    fromKey: "companyId",
-    toKey: () => companySchema.id,
-    schema: () => companySchema,
-  }),
-};
+const userSchema = schema({
+  _tableName: "users",
+  email: s
+    .varchar({ length: 255 })
+    .client(({ sql }) => sql)
+    .validation(({ client }) => client.email().toLowerCase()),
+
+  age: s.int().validation(({ sql }) => sql.min(18).max(120)),
+});
 ```
 
-### SQL Types
+## Why This Flow?
 
-Built-in SQL type definitions:
+The flow matches how data moves through your application:
+
+1. **SQL**: Database constraints and types
+2. **Initial State**: What shape new records take before persistence
+3. **Client**: How data looks in your UI/API
+4. **Validation**: Business rules applied to user input
+5. **Transform**: Convert between database and client representations
+
+Each step can reference previous steps, creating a pipeline:
 
 ```typescript
-shape.int({ nullable: true });
-shape.varchar({ length: 255 });
-shape.boolean();
-shape.date();
-shape.datetime();
-shape.text();
-shape.longtext();
+const orderSchema = schema({
+  _tableName: "orders",
+  status: s
+    .varchar({ length: 20 })
+    // 1. SQL: Simple varchar in database
+    .initialState(z.literal("draft"), () => "draft")
+    // 2. Initial: New orders start as 'draft'
+    .client(({ sql }) => z.enum(["draft", "pending", "shipped", "delivered"]))
+    // 3. Client: Enforce enum on client
+    .validation(({ client }) => client),
+  // 4. Validation: Use same rules as client
+
+  totalPrice: s
+    .int()
+    // 1. SQL: Store as cents (integer)
+    .client(() => z.number().multipleOf(0.01))
+    // 2. Client: Work with dollars (decimal)
+    .transform({
+      toClient: (cents) => cents / 100,
+      toDb: (dollars) => Math.round(dollars * 100),
+    }),
+  // 3. Transform: Automatically convert between cents and dollars
+});
 ```
 
-### Validation
+This approach ensures type safety throughout your entire data lifecycle while keeping transformations co-located with your schema definition.
 
-Add Zod validation to your schemas:
+## Real-World Example
+
+Here's a complete example showing the power of the flow:
 
 ```typescript
-const userSchema = {
+const userSchema = schema({
   _tableName: "users",
-  email: shape
-    .sql({ type: "varchar", length: 255 })
-    .validation(({ sql }) => sql.email().toLowerCase()),
-  password: shape
-    .sql({ type: "varchar", length: 255 })
-    .validation(({ sql }) =>
-      sql
-        .min(8)
-        .regex(/[A-Z]/, "Must contain uppercase letter")
-        .regex(/[0-9]/, "Must contain number")
+  id: s.int({ pk: true }).initialState(z.string().uuid(), () => uuidv4()),
+
+  email: s.varchar({ length: 255 }).validation(({ sql }) => sql.email()),
+
+  metadata: s
+    .text()
+    .initialState(
+      z.object({
+        preferences: z.object({
+          theme: z.enum(["light", "dark"]),
+          notifications: z.boolean(),
+        }),
+      }),
+      () => ({ preferences: { theme: "light", notifications: true } })
+    )
+    .client(({ initialState }) => initialState)
+    .transform({
+      toClient: (json) => JSON.parse(json),
+      toDb: (obj) => JSON.stringify(obj),
+    }),
+});
+
+const userRelations = schemaRelations(userSchema, (rel) => ({
+  posts: rel
+    .hasMany({
+      fromKey: "id",
+      toKey: () => postRelations.userId,
+      defaultCount: 0,
+    })
+    .validation(({ client }) =>
+      client.min(1, "User must have at least one post")
     ),
-  birthDate: shape
-    .sql({ type: "date" })
-    .validation(({ sql }) => sql.min(new Date("1900-01-01")).max(new Date())),
-};
+}));
+
+// Generate schemas
+const { sqlSchema, clientSchema, validationSchema, defaultValues } =
+  createSchema(userSchema, userRelations);
+
+// Use in your app
+const newUser = defaultValues; // Fully typed with defaults
+const validated = validationSchema.parse(userInput); // Runtime validation
+const dbUser = toDb(validated); // Transform for database
+const apiUser = toClient(dbUser); // Transform for API
 ```
 
-## Type Safety
+## Relationships
 
-The library provides full type inference:
+Define relationships that are type-safe across all layers:
 
 ```typescript
-const { sqlSchema, clientSchema, validationSchema, defaultValues } =
-  createSchema(userSchema);
-
-// These are fully typed:
-type DBUser = z.infer<typeof sqlSchema>;
-type ClientUser = z.infer<typeof clientSchema>;
-type ValidationUser = z.infer<typeof validationSchema>;
-const defaults: typeof defaultValues = {
-  // TypeScript will ensure this matches your schema
-};
+const messageSchema = schema({
+  _tableName: "messages",
+  id: s.int({ pk: true }).initialState(z.string(), () => uuidv4()),
+  content: s.text(),
+  timestamp: s.datetime(),
+});
+
+const messageRelations = schemaRelations(messageSchema, (rel) => ({
+  recipients: rel
+    .hasMany({
+      fromKey: "id",
+      toKey: () => recipientRelations.messageId,
+    })
+    .validation(({ sql }) => sql.min(1, "Must have at least one recipient")),
+}));
+
+// The flow works with relationships too!
+const { clientSchema } = createSchema(messageSchema, messageRelations);
+type Message = z.infer<typeof clientSchema>;
+// {
+//   id: string | number;
+//   content: string;
+//   timestamp: Date;
+//   recipients: Array<Recipient>;
+// }
 ```
 
 ## License

package/dist/cli.js

@@ -6,38 +6,48 @@ import { generateSQL } from "./generateSQL.js";
 import { unlink, writeFile } from "fs/promises";
 import { spawnSync } from "child_process";
 const program = new Command();
-program.command("generate-sql <file>").action(async (file) => {
+program
+    .name("cogsbox-shape")
+    .description("CLI for cogsbox-shape schema tools")
+    .version("0.5.70");
+program
+    .command("generate-sql <file>")
+    .description("Generate SQL from your schema definitions")
+    .option("-o, --output <path>", "Output SQL file path", "./cogsbox-shape-sql.sql")
+    .option("--no-foreign-keys", "Generate SQL without foreign key constraints")
+    .action(async (file, options) => {
     try {
         const fullPath = path.resolve(process.cwd(), file);
         if (file.endsWith(".ts")) {
-            // Create a virtual module that imports and outputs the schema
+            // Create a virtual module that imports and USES the schema directly
             const virtualModule = `
-        import { schemas } from '${pathToFileURL(fullPath).href}';
-        console.log(JSON.stringify(schemas));
-      `;
+    import { schemas } from '${pathToFileURL(fullPath).href}';
+    import { generateSQL } from '${pathToFileURL(path.join(process.cwd(), "dist/generateSQL.js")).href}';
+    
+    generateSQL(schemas, '${options.output}', { includeForeignKeys: ${options.foreignKeys !== false} })
+      .then(() => console.log('Done'))
+      .catch(err => console.error(err));
+  `;
             // Write this to a temporary file
             const tmpFile = path.join(path.dirname(fullPath), ".tmp-schema-loader.ts");
             await writeFile(tmpFile, virtualModule, "utf8");
             const result = spawnSync("npx", ["tsx", tmpFile], {
                 encoding: "utf8",
-                stdio: ["inherit", "pipe", "pipe"],
+                stdio: "inherit",
             });
             // Clean up temp file
             await unlink(tmpFile).catch(() => { });
             if (result.error) {
                 throw result.error;
             }
-            if (result.stderr) {
-                console.error("stderr:", result.stderr);
-            }
-            const schema = JSON.parse(result.stdout);
-            await generateSQL(schema);
         }
         else {
             const schema = await import(pathToFileURL(fullPath).href);
-            await generateSQL(schema.schemas);
+            await generateSQL(schema.schemas, options.output, {
+                includeForeignKeys: options.foreignKeys,
+            });
         }
-        console.log("Generated SQL successfully");
+        console.log(`Generated SQL successfully at ${options.output}`);
     }
     catch (error) {
         console.error("Error:", error);

package/dist/generateSQL.d.ts

@@ -1,6 +1,7 @@
-import type { Schema } from "./schema";
-type SchemaInput = Record<string, Schema<any>> | {
-    schemas: Record<string, Schema<any>>;
+type SchemaInput = Record<string, any> | {
+    schemas: Record<string, any>;
 };
-export declare function generateSQL(input: SchemaInput, outputPath?: string): Promise<string>;
+export declare function generateSQL(input: SchemaInput, outputPath?: string, options?: {
+    includeForeignKeys?: boolean;
+}): Promise<string>;
 export {};

package/dist/generateSQL.js

@@ -1,5 +1,4 @@
 import fs from "fs/promises";
-// SQL Type mapping
 const sqlTypeMap = {
     int: "INTEGER",
     varchar: (length = 255) => `VARCHAR(${length})`,
@@ -17,46 +16,105 @@ function isWrappedSchema(input) {
         input.schemas !== null &&
         typeof input.schemas === "object");
 }
-export async function generateSQL(input, outputPath = "cogsbox-shape-sql.sql") {
+export async function generateSQL(input, outputPath = "cogsbox-shape-sql.sql", options = { includeForeignKeys: true }) {
     if (!input) {
         throw new Error("No schema input provided");
     }
-    // Extract schemas using type guard
     const schemas = isWrappedSchema(input) ? input.schemas : input;
     if (!schemas || typeof schemas !== "object") {
         throw new Error("Invalid schemas input");
     }
     const sql = [];
-    // Generate SQL for each schema
     for (const [name, schema] of Object.entries(schemas)) {
         const tableName = schema._tableName;
+        if (!tableName) {
+            console.warn(`Skipping schema '${name}' - no _tableName found`);
+            continue;
+        }
         const fields = [];
         const foreignKeys = [];
-        // Process each field in the schema
         for (const [fieldName, field] of Object.entries(schema)) {
-            if (fieldName === "_tableName")
+            // Skip metadata fields
+            const f = field; // Just cast once
+            console.log(`Processing field: ${fieldName}`, f);
+            // Skip metadata fields
+            if (fieldName === "_tableName" ||
+                fieldName === "SchemaWrapperBrand" ||
+                fieldName.startsWith("__") ||
+                typeof f !== "object" ||
+                !f)
+                continue;
+            // Handle reference fields
+            if (f.type === "reference" && f.to) {
+                const referencedField = f.to();
+                const targetTableName = referencedField.__parentTableType._tableName;
+                const targetFieldName = referencedField.__meta._key;
+                console.log(`Found reference field: ${fieldName} -> ${targetTableName}.${targetFieldName}`);
+                fields.push(`  ${fieldName} INTEGER NOT NULL`);
+                if (options.includeForeignKeys) {
+                    foreignKeys.push(`  FOREIGN KEY (${fieldName}) REFERENCES ${targetTableName}(${targetFieldName})`);
+                }
                 continue;
-            // Handle regular fields
-            if ("sql" in field) {
-                const { type, nullable, pk, length } = field.sql;
+            }
+            // Get the actual field definition from enriched structure
+            let fieldDef = f;
+            // If it's an enriched field, extract the original field definition
+            if (f.__meta && f.__meta._fieldType) {
+                fieldDef = f.__meta._fieldType;
+            }
+            // Now check if fieldDef has config
+            if (fieldDef && fieldDef.config && fieldDef.config.sql) {
+                const sqlConfig = fieldDef.config.sql;
+                // Handle relation configs (hasMany, hasOne, etc.)
+                if (["hasMany", "hasOne", "belongsTo", "manyToMany"].includes(sqlConfig.type)) {
+                    // Only belongsTo creates a column
+                    if (sqlConfig.type === "belongsTo" &&
+                        sqlConfig.fromKey &&
+                        sqlConfig.schema) {
+                        fields.push(`  ${sqlConfig.fromKey} INTEGER`);
+                        if (options.includeForeignKeys) {
+                            const targetSchema = sqlConfig.schema();
+                            foreignKeys.push(`  FOREIGN KEY (${sqlConfig.fromKey}) REFERENCES ${targetSchema._tableName}(id)`);
+                        }
+                    }
+                    continue;
+                }
+                // Handle regular SQL types
+                const { type, nullable, pk, length, default: defaultValue } = sqlConfig;
+                if (!sqlTypeMap[type]) {
+                    console.warn(`Unknown SQL type: ${type} for field ${fieldName}`);
+                    continue;
+                }
                 const sqlType = typeof sqlTypeMap[type] === "function"
                     ? sqlTypeMap[type](length)
                     : sqlTypeMap[type];
-                fields.push(`  ${fieldName} ${sqlType}${pk ? " PRIMARY KEY" : ""}${nullable ? "" : " NOT NULL"}`);
-            }
-            // Handle relations
-            if (typeof field === "function") {
-                const relation = field();
-                if (relation.type === "belongsTo") {
-                    fields.push(`  ${relation.fromKey} INTEGER`);
-                    foreignKeys.push(`  FOREIGN KEY (${relation.fromKey}) REFERENCES ${relation.schema._tableName}(id)`);
+                let fieldDefStr = `  ${fieldName} ${sqlType}`;
+                if (pk)
+                    fieldDefStr += " PRIMARY KEY AUTO_INCREMENT";
+                if (!nullable && !pk)
+                    fieldDefStr += " NOT NULL";
+                // Handle defaults
+                if (defaultValue !== undefined &&
+                    defaultValue !== "CURRENT_TIMESTAMP") {
+                    fieldDefStr += ` DEFAULT ${typeof defaultValue === "string" ? `'${defaultValue}'` : defaultValue}`;
+                }
+                else if (defaultValue === "CURRENT_TIMESTAMP") {
+                    fieldDefStr += " DEFAULT CURRENT_TIMESTAMP";
                 }
+                fields.push(fieldDefStr);
             }
         }
-        // Combine fields and foreign keys
-        const allFields = [...fields, ...foreignKeys];
+        // Combine fields and foreign keys based on option
+        const allFields = options.includeForeignKeys
+            ? [...fields, ...foreignKeys]
+            : fields;
         // Create table SQL
-        sql.push(`CREATE TABLE ${tableName} (\n${allFields.join(",\n")}\n);\n`);
+        if (allFields.length > 0) {
+            sql.push(`CREATE TABLE ${tableName} (\n${allFields.join(",\n")}\n);\n`);
+        }
+        else {
+            console.warn(`Warning: Table ${tableName} has no fields`);
+        }
     }
     // Write to file
     const sqlContent = sql.join("\n");

package/package.json

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