cogsbox-shape 0.5.68 → 0.5.70

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/schema.d.ts

@@ -98,7 +98,7 @@ export type RelationConfig<T extends Schema<any>> = (BaseRelationConfig<T> & {
 type Stage = "sql" | "relation" | "new" | "client" | "validation" | "done";
 type StageMethods = {
     sql: "initialState" | "client" | "validation" | "transform";
-    relation: "initialState" | "client" | "validation" | "transform";
+    relation: "validation" | "transform";
     new: "client" | "validation" | "transform";
     client: "validation" | "transform";
     validation: "transform";
@@ -307,7 +307,7 @@ export declare function schemaRelations<TSchema extends Schema<any>, RefObject e
             _key: K;
             _fieldType: RefObject[K];
         };
-        __parentTableType: TSchema;
+        __parentTableType: TSchema & RefObject;
     };
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cogsbox-shape",
-    "version": "0.5.68",
+    "version": "0.5.70",
     "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",
@@ -49,7 +49,7 @@
         "prettier": "^3.1.1",
         "typescript": "^5.3.3",
         "vitest": "^3.2.0",
-        "zod": "^3.25.67"
+        "zod": "^4.25.67"
     },
     "peerDependencies": {
         "zod": "^3.22.4"