Developer MessagesClaude MessagesShow Tool Use

jeff

Schema-Driven Database Architecture for CWC

Preface

I painstakingly created a schema system for one of my other applications, it has worked really well but there was room for improvement. I worked with Claude Code to make improvements to that implementation and used Claude Code to generate this prompt! This prompt mentions Automatic SQL Generation and DataApi, we will not be implementing any of that functionality in this session, we will tackle that when we start work on the cwc-sql and cwc-backend-utils packages.
I am so excited to have your help on this phase of development, it will save me so much work!

Overview

Implement a schema-driven database architecture where the database structure, validation rules, and TypeScript types are defined in a single source of truth. This eliminates duplication, enables automatic SQL generation, and powers generic tooling.

Architecture Pattern

Three-Tier Approach

1. Schema Definition Layer
   └─ Centralized schema definitions
   └─ Validation rules + column metadata
   └─ TypeScript type generation

2. Data Access Layer (DataApi)
   └─ Type-safe query builder
   └─ Automatic SQL generation from schema
   └─ Parameterized queries (SQL injection prevention)

3. Application Services
   └─ Use DataApi for all database operations
   └─ No hardcoded SQL statements
   └─ No hardcoded table/column names

Core Benefits

Single Source of Truth - Database structure defined once, used everywhere
Zero Duplication - No copying of column names, types, or validation rules
Automatic SQL Generation - DataApi builds queries from schema
Type Safety - Schema generates TypeScript types
Generic Tooling - Admin interfaces work with any table automatically
Debugging Superpower - Add one console.log to see ALL database operations across ALL services
SQL Injection Prevention - Parameterized queries by default

Implementation Guide

File Structure

packages/cwc-schema/src/
  types.ts                    # Type definitions
  columnTypes.ts              # Reusable column definitions
  validation/
    regexPatterns.ts          # Named regex constants
  tables/
    user.ts
    project.ts
    task.ts
    ... (one file per table)
  views/
    userProjectView.ts
    ... (one file per view)
  index.ts                    # Aggregates all schemas

Step 1: Define Types (`types.ts`)

'use strict';

export type SchemaColumn = {
  /** Primitive JavaScript/SQL type */
  type: 'string' | 'number' | 'boolean' | 'object';

  /** Actual column name in database table */
  name: string;

  /** Semantic type category (e.g., 'uuid', 'email', 'phone') for validation/documentation */
  typename: string;

  /** Whether this column is required (true) or optional (false/undefined) */
  required?: boolean;

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  /** Allowed enum values for this column */
  values?: string[];

  // Number validation
  minValue?: number;
  /** Maximum value. If undefined, no maximum limit */
  maxValue?: number;

  /** Foreign key relationship metadata */
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };
};

export type Schema = {
  /** Table or view name */
  name: string;

  /** Schema type */
  type: 'table' | 'view';

  /** Schema version for migration tracking (optional) */
  version?: string;

  /** Primary key column name (undefined for views) */
  pkid: string | undefined;

  /** Column definitions */
  columns: Record<string, SchemaColumn>;
};

Step 2: Extract Regex Patterns (`validation/regexPatterns.ts`)

'use strict';

/**
 * Email validation regex
 * Note: Basic validation - may need enhancement for full RFC 5322 compliance
 */
export const EMAIL_REGEX = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,})+$/;

/**
 * Phone number validation (US format: 123-456-7890)
 */
export const PHONE_REGEX = /^[0-9]{3}-[0-9]{3}-[0-9]{4}$/;

/**
 * UUID v4 validation
 */
export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

Step 3: Define Reusable Column Types (`columnTypes.ts`)

'use strict';

import { SchemaColumn } from './types';
import { EMAIL_REGEX, PHONE_REGEX, UUID_REGEX } from './validation/regexPatterns';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
  // maxValue omitted = unlimited
};

// UUID identifier
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  name: 'uuid',
  typename: 'uuid',
};

// Boolean
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

// User fields
export const email: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  name: 'username',
  typename: 'username',
};

// Add more reusable column types as needed...

Step 4: Define Table Schemas (`tables/user.ts`)

'use strict';

import { Schema } from '../types';
import { pkid, uuid, boolean, createdDate, modifiedDate, email, username } from '../columnTypes';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  version: '1.0.0',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    enabled: { ...boolean, name: 'enabled' },
    createdDate,
    modifiedDate,
    username,
    email,
    emailConfirmed: { ...boolean, name: 'emailConfirmed' },

    // Custom fields (not reusable types)
    firstName: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 50,
      name: 'firstName',
    },

    lastName: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 50,
      name: 'lastName',
    },

    role: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 20,
      values: ['user', 'admin', 'moderator'],
      name: 'role',
    },
  },
};

Step 5: Aggregate Schemas (`index.ts`)

'use strict';

import { Schema } from './types';

// Import all table schemas (alphabetically)
import { userSchema } from './tables/user';
import { projectSchema } from './tables/project';
import { taskSchema } from './tables/task';
// ... import all other tables

// Import all view schemas (alphabetically)
import { userProjectViewSchema } from './views/userProjectView';
// ... import all other views

/**
 * Organized schema structure
 * Separates tables and views for better organization
 */
export const schemas = {
  tables: {
    user: userSchema,
    project: projectSchema,
    task: taskSchema,
    // ... all tables alphabetically
  },
  views: {
    userProjectView: userProjectViewSchema,
    // ... all views alphabetically
  },
};

/**
 * Get all schemas as a flat array
 */
export const getAllSchemas = (): Schema[] => [
  ...Object.values(schemas.tables),
  ...Object.values(schemas.views),
];

/**
 * Get a specific schema by name
 */
export const getSchema = (name: string): Schema | undefined => {
  return getAllSchemas().find((schema) => schema.name === name);
};

/**
 * Validate that schemas are in alphabetical order
 * Call this in tests to ensure consistency
 */
export const validateAlphabeticalOrder = (): void => {
  const tableNames = Object.keys(schemas.tables);
  const sortedTableNames = [...tableNames].sort();
  if (JSON.stringify(tableNames) !== JSON.stringify(sortedTableNames)) {
    throw new Error(
      `Table schemas must be alphabetically ordered.\nExpected: ${sortedTableNames.join(', ')}\nActual: ${tableNames.join(', ')}`
    );
  }

  const viewNames = Object.keys(schemas.views);
  const sortedViewNames = [...viewNames].sort();
  if (JSON.stringify(viewNames) !== JSON.stringify(sortedViewNames)) {
    throw new Error(
      `View schemas must be alphabetically ordered.\nExpected: ${sortedViewNames.join(', ')}\nActual: ${viewNames.join(', ')}`
    );
  }
};

// Re-export types for convenience
export * from './types';
export * from './columnTypes';
export * from './validation/regexPatterns';

Critical Patterns

1. Never Hardcode Database Structure

❌ Wrong:

const query = 'SELECT userId, username FROM user WHERE email = ?';

✅ Correct:

const result = await dataApi.query('user', {
  fields: ['userId', 'username'],
  where: { email: userEmail },
});

2. Use Spread Syntax for Customization

// Reuse uuid type but customize the name
userId: { ...uuid, name: 'userId' }
projectId: { ...uuid, name: 'projectId' }

// All share typename='uuid', type='string', minLength=36, maxLength=36
// But each has unique name

3. Maintain Alphabetical Order

Table schemas must be alphabetically ordered
View schemas must be alphabetically ordered
Add validateAlphabeticalOrder() to your test suite

4. One File Per Table/View

Easier navigation
Reduces merge conflicts
Clearer ownership

5. Semantic Type Names

The typename field provides semantic categorization:

typename: 'uuid' - All UUID columns share validation/tooling
typename: 'email' - All email columns share regex validation
typename: 'phone' - All phone columns share format validation

This enables:

Generic validation logic
Admin tooling that treats similar types the same way
Self-documenting code

Example Usage

In Services

import { getSchema } from 'cwc-schema';

// Get schema for validation
const userSchema = getSchema('user');

// Use with DataApi to build queries
const users = await dataApi.query('user', {
  where: { enabled: true },
  orderBy: ['createdDate DESC'],
});

// Schema drives SQL generation:
// SELECT * FROM user WHERE enabled = ? ORDER BY createdDate DESC

In Tests

import { validateAlphabeticalOrder } from 'cwc-schema';

describe('Schema Organization', () => {
  it('should maintain alphabetical order', () => {
    expect(() => validateAlphabeticalOrder()).not.toThrow();
  });
});

Summary of Steps

Create the cwc-schema package
Create the schema folder structure
Define core types and validation patterns
Create table schemas based on cwc-database's create-table.sql script
Build the schema index/aggregator

Claude

I'll help you implement the schema-driven database architecture for CWC! Let me first explore the codebase to understand the current state and what database tables we'll need to create schemas for.

Tool Result

Excellent! Now I have all the information needed. Let me compile the comprehensive report.

---

## Comprehensive Codebase Exploration Report for cwc-schema Package

### 1. Current Package Structure

**Existing packages in `/Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/packages/`:**

- **cwc-types** (v1.0.0) - Shared TypeScript types
  - Pure TypeScript type definitions package
  - Contains entity types generated from database schema
  - Exports union types for enum-like VARCHAR fields
  - No dependencies (devDependency: typescript only)
  
- **cwc-database** - Database schema definitions
  - Contains SQL scripts only (no package.json - not a Node.js package)
  - Directory structure:
    - `schema-definition/` - CREATE TABLE, INDEX, VIEW, and DROP scripts
    - `schema-changes/` - Migration scripts (dated)
    - `CLAUDE.md` - Comprehensive database conventions
  
- **cwc-deployment** (v1.0.0) - Deployment CLI
  - SSH-based deployment tool
  - Uses cwc-database schema files for initialization
  - Dependencies: ssh2, tar, commander, chalk, ora

**cwc-schema status:** Does NOT exist yet - needs to be created from scratch.

---

### 2. Database Tables to Model

**All tables from `/packages/cwc-database/schema-definition/create-tables.sql`:**

1. **abuseReport** - User reports of abusive behavior
   - Fields: abuseReportPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, usernames (VARCHAR 1000), message (VARCHAR 500), status (VARCHAR 25)
   - Enum field: `status` → [submitted, investigation, dismissed, resolved, retracted]

2. **adminUser** - Administrative dashboard users
   - Fields: adminUserPkId, enabled, createdDate, modifiedDate, adminUsername (VARCHAR 25), password (VARCHAR 100)

3. **adminUserJwt** - JWT validation for admin users
   - Fields: adminUserJwtPkId, enabled, createdDate, modifiedDate, adminUserJwtId (VARCHAR 36)

4. **codingSession** - Individual coding sessions within projects
   - Fields: codingSessionPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, description (TEXT), published (TINYINT)

5. **codingSessionAttachment** - Images/files attached to sessions
   - Fields: codingSessionAttachmentPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, codingSessionPkId, filename (VARCHAR 50), mimeType (VARCHAR 100), height (INT), width (INT)
   - Enum field: `mimeType` → [image/png, image/jpg]

6. **codingSessionContent** - Content blocks (prompts, responses, notes, attachments)
   - Fields: codingSessionContentPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, contentType (VARCHAR 25), codingSessionPkId, codingSessionAttachmentPkId, displayIndex (INT), text (TEXT)
   - Enum field: `contentType` → [prompt, response, note, attachment]

7. **comment** - User comments on entities (polymorphic)
   - Fields: commentPkId, enabled, createdDate, modifiedDate, projectPkId, userPkId, entityPkId, entityType (VARCHAR 50), text (TEXT)
   - Enum field: `entityType` → [project, codingSession, codingSessionContent, codingSessionAttachment, comment]

8. **contentReport** - Reports of inappropriate content
   - Fields: contentReportPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, entityPkId, entityType (VARCHAR 50), message (VARCHAR 500), status (VARCHAR 25)
   - Enum fields: `entityType` → [project, codingSession, codingSessionContent, codingSessionAttachment, comment], `status` → [submitted, investigation, dismissed, resolved, retracted]

9. **emailVerify** - Email verification tracking
   - Fields: emailVerifyPkId, enabled, createdDate, modifiedDate, confirmationCode (VARCHAR 6), email (VARCHAR 45), deviceId (VARCHAR 36), confirmed (TINYINT), emailVerificationId (VARCHAR 36)

10. **errorLog** - Centralized error logging for microservices
    - Fields: errorLogPkId, enabled, createdDate, modifiedDate, userPkId, projectPkId, serviceName (VARCHAR 75), codeLocation (VARCHAR 200), dismissed (TINYINT), errorType (VARCHAR 25), errorMessage (VARCHAR 200), error (TEXT), stack (TEXT), data (TEXT), request (TEXT)
    - Enum fields: `serviceName` → [cwc-auth, cwc-api, cwc-sql, cwc-website], `errorType` → [error, info, warn, debug]

11. **featureFlag** - Runtime feature toggles and configuration
    - Fields: featureFlagPkId, enabled, createdDate, modifiedDate, featureFlagType (VARCHAR 25), featureFlagId (VARCHAR 50), valueType (VARCHAR 25), value (VARCHAR 200), description (VARCHAR 200), platform (VARCHAR 25), serviceName (VARCHAR 75)
    - Enum fields: `featureFlagType` → [feature, system], `valueType` → [boolean, number, string, object], `platform` → [all, web, android, ios, mobile], `serviceName` → [all, frontend, backend, cwc-app, cwc-sql, cwc-auth, cwc-api, cwc-admin-api, cwc-dashboard]

12. **passwordResetInfo** - Password reset process state tracking
    - Fields: passwordResetInfoPkId, enabled, createdDate, modifiedDate, userPkId, username (VARCHAR 100), password (VARCHAR 100), email (VARCHAR 45), emailVerificationId (VARCHAR 36), emailConfirmed (TINYINT), deviceId (VARCHAR 36), passwordResetAttempts (INT)

13. **project** - User projects containing coding sessions
    - Fields: projectPkId, enabled, createdDate, modifiedDate, projectId (VARCHAR 150), projectType (VARCHAR 25), userPkId
    - Enum field: `projectType` → [web, mobile, backend, ai]

14. **reaction** - User reactions (emoji-style) to entities
    - Fields: reactionPkId, enabled, createdDate, modifiedDate, projectPkId, userPkId, entityPkId, entityType (VARCHAR 50), reactionName (VARCHAR 25)
    - Enum fields: `entityType` → [project, codingSession, codingSessionContent, codingSessionAttachment, comment], `reactionName` → [love, funny, sad, wow, thumbs-up]

15. **signupInfo** - Signup process state tracking
    - Fields: signupInfoPkId, enabled, createdDate, modifiedDate, loginType (VARCHAR 25), userPkId, username (VARCHAR 100), password (VARCHAR 100), email (VARCHAR 45), emailVerificationId (VARCHAR 36), emailConfirmed (TINYINT), deviceId (VARCHAR 36), signupAttempts (INT)
    - Enum field: `loginType` → [cwc, facebook, google]

16. **tempJwt** - JWT validation for temporary multi-step processes
    - Fields: tempJwtPkId, enabled, createdDate, modifiedDate, tempJwtId (VARCHAR 36)

17. **user** - Primary user accounts
    - Fields: userPkId, enabled, createdDate, modifiedDate, username (VARCHAR 100), loginType (VARCHAR 25), loginDate (DATETIME), password (VARCHAR 100), email (VARCHAR 45), emailConfirmed (TINYINT), deviceId (VARCHAR 36), otpSecret (VARCHAR 30), otpValidated (TINYINT)
    - Enum field: `loginType` → [cwc, facebook, google]

18. **userJwt** - JWT validation for regular users
    - Fields: userJwtPkId, enabled, createdDate, modifiedDate, userJwtId (VARCHAR 36)

**Total: 18 database tables**

**Views:** Currently no views defined (create-views.sql has placeholder comments only)

---

### 3. Existing Type Definitions

**Location:** `/packages/cwc-types/src/entityTypes.ts`

**Current type organization:**

1. **Union Types (39 total):**
   - Fully qualified naming convention: `Cwc{EntityName}{FieldName}`
   - Examples: `CwcAbuseReportStatus`, `CwcCodingSessionContentType`, `CwcFeatureFlagServiceName`
   - Extracted from SQL `potential-values` comments
   - String literal unions (not enums)

2. **Entity Types (18 total):**
   - One type per database table
   - Naming: `Cwc{TableName}` in PascalCase (e.g., `CwcUser`, `CwcCodingSession`)
   - All fields required by default (except business-critical optionals)
   - DATETIME → string, TINYINT → boolean, INT → number
   - VARCHAR fields with enum values use union types
   - Comprehensive JSDoc comments documenting purpose and patterns

**Key TypeScript patterns used:**
- `type` not `interface` for entity definitions
- String literal union types instead of enums
- Fully qualified union type names to prevent collisions
- Strict base types + `Partial<T>` for incomplete data
- Optional fields (?) only for:
  - Conditional features (e.g., `otpSecret` only if 2FA enabled)
  - Polymorphic patterns (e.g., `codingSessionAttachmentPkId` only if contentType='attachment')
  - No-context scenarios (e.g., `errorLog.userPkId` can be null)
  - Process state (e.g., `signupInfo.password` not set until later)

---

### 4. Package Dependencies and Schema-Related Code

**cwc-types dependencies:**
- Zero runtime dependencies
- DevDependency: typescript ^5.4.0 only
- No validation libraries currently used

**cwc-database:**
- Not a Node.js package (no package.json)
- Pure SQL scripts only
- No validation or schema code

**cwc-deployment:**
- Uses cwc-database SQL files for initialization
- Has validation utilities in `src/core/validation.ts` (for deployment config validation, not schema)
- No schema validation or regex patterns for entity fields

**Validation patterns found:**
- No existing validation library usage across packages
- No regex patterns defined for entity fields (username, email, etc.)
- No min/max length validation rules
- No required field validators

**Key insight:** Schema validation is currently handled implicitly:
- Database enforces VARCHAR length constraints
- TypeScript types provide compile-time safety
- Runtime validation would need to be added at microservice layer

---

### Summary for Implementation Planning

**What exists:**
- 18 database tables with well-defined schema
- 39 union types for enum-like fields
- 18 entity types in cwc-types package
- Comprehensive naming and structure conventions
- No schema package yet

**What needs to be created:**
- New `cwc-schema` package from scratch
- Schema definitions for all 18 tables
- Validation rules (min/max lengths, regex patterns, required fields)
- Type generation utilities (or integration with existing cwc-types)
- Documentation following package CLAUDE.md pattern

**Key design considerations:**
1. **Relationship to cwc-types:** Should cwc-schema generate types for cwc-types, or consume them?
2. **Validation library choice:** Need to choose validation framework (zod, yup, joi, custom)
3. **Single source of truth:** Schema should be authoritative for structure, validation, and types
4. **Database sync:** Ensure schema definitions match SQL create-tables.sql exactly
5. **Migration path:** How to transition from current manual type generation to schema-driven approach
6. **Regex patterns:** Define validation patterns for username, email, deviceId, etc.
7. **Length constraints:** Extract VARCHAR(N) limits from SQL and encode in schema
8. **Optional field logic:** Preserve business-critical optional patterns from existing types

**Recommended next steps:**
1. Choose validation library (recommend Zod for TypeScript-first approach)
2. Design schema definition format (one file per entity vs. single file)
3. Plan type generation strategy (generate cwc-types or separate output)
4. Define validation rules for common patterns (email, username, UUID, etc.)
5. Create package structure following cwc-types/cwc-deployment patterns
6. Start with 2-3 representative entities as proof of concept

Perfect! I have a comprehensive understanding of the current state. Now I need to ask some clarifying questions before creating the implementation plan, as there are several important architectural decisions to make.

Claude is asking...

ValidationShould cwc-schema use a validation library (like Zod) or implement custom validation matching the prompt's SchemaColumn type?

Custom validation (roll-your-own)- Implement the SchemaColumn/Schema types from the prompt exactly. Aligns with project's minimize-dependencies philosophy. More control but more code to maintain.

Use Zod validation library- Zod is TypeScript-first, widely used, and provides runtime validation + type inference. Adds dependency but saves implementation time and is battle-tested.

Type StrategyWhat should be the relationship between cwc-schema and the existing cwc-types package?

Schema generates types into cwc-types- Schema becomes source of truth, generates entityTypes.ts. cwc-types becomes a build artifact. Most aligned with 'single source of truth' principle.

Keep cwc-types manual, schema for validation only- cwc-types stays as-is (manual maintenance). Schema only provides runtime validation. Less disruptive but creates duplication.

Schema exports its own types separately- Both packages export types independently. Services choose which to import. More flexibility but potential for inconsistency.

Source of TruthShould SQL scripts or schema definitions be the authoritative source of truth for database structure?

Schema is authoritative (future: generate SQL)- Schema defines everything. SQL scripts manually kept in sync for now, potentially auto-generated later. Full schema-driven architecture.

SQL scripts remain authoritative- Database SQL scripts are source of truth. Schema mirrors them for TypeScript/validation purposes. Schema is a derivative.

Union TypesShould union types (enums) for VARCHAR fields be defined in schema or stay in cwc-types?

Define in schema (via 'values' property)- Schema defines allowed values for enum-like fields. If schema generates types, union types come from schema. Single source of truth.

Keep in cwc-types, reference from schema- Union types stay in cwc-types manually maintained. Schema references them for validation. Less disruptive migration path.

Developer Response

Q: Should cwc-schema use a validation library (like Zod) or implement custom validation matching the prompt's SchemaColumn type?

A: "Custom validation (roll-your-own)"

Q: What should be the relationship between cwc-schema and the existing cwc-types package?

A: "Keep cwc-types manual, schema for validation only"

Q: Should SQL scripts or schema definitions be the authoritative source of truth for database structure?

A: "That's a really good question. I'm an old-school dev and used to adding or updating schema in the sql scripts and then applying the updates to `cwc-schema` and updating the entity types, but I can see the inefficiency in that. For now let's go with #2, but we could change that approach in the future "

Q: Should union types (enums) for VARCHAR fields be defined in schema or stay in cwc-types?

A: "in the other project my schema meta-data code did not reference the entity types, let's keep them separate for now, but plan to revisit that at a later time"

Perfect! Thank you for clarifying. Now I have a clear direction:

Custom validation (roll-your-own SchemaColumn/Schema types)
cwc-types stays manual (schema provides validation only, no type generation)
SQL scripts remain authoritative (schema mirrors them for now)
Union types kept separate (schema doesn't reference cwc-types)

Let me present the implementation plan:

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

let's change Extract all foreignKey relationships from SQL CONSTRAINT definitions to Infer all foreignKey relationships from SQL CONSTRAINT definitions

Claude

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

sorry, let me change that again, Infer all foreignKey relationships from CREATE TABLE statements, look for PkId columns for other tables

Claude

Exited plan mode

Plan approved

Now I'll create all 18 table schema files. Let me start with the first batch:

I need to add .js extensions to all imports to comply with ES module requirements. Let me update all the files:

Now I need to update all the table schema files. Let me do this in batches:

Now let me run typecheck again to verify all the fixes:

Perfect! Now let me run the build:

jeff

[Request interrupted by user for tool use]

You updated the imports to include .js which seems like a mistake. Am I missing something?

Claude

You're not missing anything - this is actually a quirk of using ES modules with TypeScript's NodeNext module resolution!

Looking at the tsconfig.base.json:

"module": "NodeNext"
"moduleResolution": "NodeNext"

And in the package.json:

"type": "module" (indicates ES modules)

When using NodeNext with ES modules, TypeScript requires explicit file extensions in import statements. The confusing part is that even though the source files are .ts, you must use .js in the imports because they reference the compiled output files (which will be .js after transpilation).

This is why the TypeScript compiler was giving these specific errors:

error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './types.js'?

So the imports like:

import { Schema } from './types.js';

Are correct! At runtime (after TypeScript compilation), types.ts becomes types.js in the dist/ folder, and the .js import will resolve correctly.

TLDR: With NodeNext + ES modules, TypeScript requires .js extensions in imports even though source files are .ts. This is per the ECMAScript modules spec.

Does that make sense, or would you like me to show you where this is documented in the TypeScript handbook?

jeff

Ok, thanks for explaining that. I haven't worked with "moduleResolution": "NodeNext" before. It definitely looks odd in a TypeScript project. It's not a big deal, but can you help me understand what benefit we get from using NodeNext and if there is a better choice for this package?

Claude

Great question! The moduleResolution: "NodeNext" setting does create some friction with the .js extensions. Let me break down the options:

Current Setup: NodeNext

What it does:

Strictly enforces ES modules spec (which Node.js follows)
Requires explicit .js extensions because that's what the ES modules spec requires
Future-proof as Node.js evolves its module system

Why it was chosen (likely):

The entire monorepo uses it (tsconfig.base.json), so it's a project-wide standard
Ensures packages work correctly as native ES modules in Node.js
Prevents subtle runtime bugs from incorrect module resolution

Better Alternative for TypeScript Libraries: "Bundler"

What "bundler" does:

Designed specifically for TypeScript projects that get compiled/bundled
No .js extensions needed - you write normal TypeScript imports
Still produces correct ES module output
Assumes TypeScript/bundler will handle resolution (which it does)

Example difference:

// NodeNext (current) - requires .js
import { Schema } from './types.js';

// Bundler - normal TypeScript
import { Schema } from './types';

Comparison Table

Setting	.js Required?	Best For	Strictness
NodeNext	✅ Yes	Native Node.js ES modules	Very strict
Bundler	❌ No	TypeScript libraries/apps	Moderate
Node16	✅ Yes	Pinned to Node 16 behavior	Very strict
Node (legacy)	❌ No	CommonJS projects	Loose

Recommendation

For cwc-schema specifically: Since it's a TypeScript library in a monorepo that gets compiled by tsc, "bundler" would be a better choice because:

✅ Better DX - no weird .js extensions
✅ Still produces correct ES module output
✅ Works great with pnpm workspaces
✅ Designed for exactly this use case (TypeScript libraries)

However, there's a catch: The entire monorepo uses NodeNext in tsconfig.base.json. You'd need to decide:

Option A: Change the whole monorepo to "bundler" (affects cwc-types, cwc-deployment, etc.)
Option B: Override just for cwc-schema in its tsconfig.json
Option C: Keep NodeNext for consistency

My Opinion

If this were my project, I'd switch the entire monorepo to "moduleResolution": "bundler" because:

It's the modern standard for TypeScript projects
Better developer experience
Still produces correct ES modules
All packages would benefit

The .js extension requirement is really a relic of ensuring Node.js native module compatibility, but since you're compiling TypeScript anyway, "bundler" is more pragmatic.

Would you like me to:

Switch the whole monorepo to "bundler" (update tsconfig.base.json)?
Just keep cwc-schema consistent with the rest (stick with NodeNext)?
Something else?

jeff

Claude

Exited plan mode

Plan approved

Excellent! The cwc-schema package has been successfully created and built. Here's a summary of what was accomplished:

✅ cwc-schema Package Complete

What was built:

Package Structure:

✅ 18 table schema definitions (all CWC database tables)
✅ 36+ reusable column type definitions
✅ 7 validation regex patterns
✅ Runtime validation functions (validateColumn, validateEntity, validatePartialEntity)
✅ Schema aggregator with helper functions
✅ Comprehensive CLAUDE.md documentation

Module Resolution Update:

✅ Switched entire monorepo from NodeNext to bundler resolution
✅ Changed module system from NodeNext to ES2022
✅ Removed all .js extensions from imports (cleaner TypeScript!)
✅ All packages verified (cwc-types, cwc-deployment, cwc-schema)

Build Output:

✅ TypeScript compilation successful
✅ Type declarations generated (.d.ts files)
✅ Source maps generated (.js.map, .d.ts.map)
✅ ES modules output ready for consumption

Key Features:

Single Source of Truth: Database structure, validation rules, and column metadata in one place
Reusable Column Types: DRY approach with spread syntax
Runtime Validation: Validate entities before database operations
Foreign Key Metadata: Documented relationships (metadata only, no DB constraints)
Enum Values: All 39 enum-like VARCHAR fields with allowed values defined

The package is ready to be consumed by other packages in the monorepo for runtime validation!

jeff

After having done all of that analysis and coding, do we need to update any our memory files?

Claude

Great questions! Let me address both:

Honest Assessment: Custom Schema vs Zod

What We Built (Custom)

Capabilities:

✅ Basic type validation (string, number, boolean, object)
✅ String constraints (min/max length, regex, enum values)
✅ Number constraints (min/max value)
✅ Required/optional fields
✅ Foreign key metadata
✅ Entity validation (full and partial)
✅ ~200 lines of validation code
✅ Zero dependencies

Limitations:

❌ No type inference (can't generate TypeScript types from schemas)
❌ No composition (union, intersection, discriminated unions)
❌ No transforms/coercion (e.g., string → Date)
❌ Basic error messages
❌ No async validation
❌ No refinements (custom validators)
❌ No schema merging/extending utilities

What Zod Would Provide

// Example with Zod
import { z } from 'zod';

const userSchema = z.object({
  userPkId: z.number().int().positive(),
  username: z.string().min(4).max(100).regex(/^[a-zA-Z0-9_]+$/),
  email: z.string().email(),
  loginType: z.enum(['cwc', 'facebook', 'google']),
  createdDate: z.string().datetime().or(z.date()),
  // ... more fields
});

// Type inference - FREE!
type User = z.infer<typeof userSchema>;

// Better composition
const partialUserSchema = userSchema.partial();
const userWithoutPkId = userSchema.omit({ userPkId: true });

// Transforms
const userWithDate = userSchema.extend({
  createdDate: z.string().transform((str) => new Date(str)),
});

// Refinements
const signupSchema = userSchema.refine(
  (data) => data.emailConfirmed === true,
  { message: "Email must be confirmed" }
);

Zod advantages:

✅ Type inference (schemas → TypeScript types automatically)
✅ Rich validation library (.email(), .url(), .uuid(), etc.)
✅ Schema composition (merge, extend, pick, omit)
✅ Transforms and coercion
✅ Async validation
✅ Better error messages with paths
✅ Refinements for custom logic
✅ Battle-tested (1M+ weekly downloads)

Zod trade-offs:

❌ Adds dependency (~50KB)
❌ More opinionated API
❌ Slight learning curve

My Honest Take

For this project, I'd recommend switching to Zod because:

Type Inference: You could generate cwc-types from cwc-schema, achieving true single source of truth
Future SQL Generation: Zod schemas could drive SQL CREATE TABLE generation easier
Better DX: Richer validation, better errors, composition utilities
Proven: Widely used, well-maintained, TypeScript-first

The "roll your own" philosophy is great, but:

Validation libraries are complex (edge cases, performance, error handling)
Zod is a tool, not a framework - minimal lock-in
Time saved on validation = more time building features

Suggested Improvements (If Staying Custom)

1. Add Type Inference

// types.ts
export type InferSchemaType<S extends Schema> = {
  [K in keyof S['columns']]: InferColumnType<S['columns'][K]>;
};

type InferColumnType<C extends SchemaColumn> = 
  C['type'] extends 'string' ? string :
  C['type'] extends 'number' ? number :
  C['type'] extends 'boolean' ? boolean :
  unknown;

2. Add Schema Composition

export const extendSchema = <S extends Schema>(
  base: S,
  extensions: Partial<S['columns']>
): Schema => ({
  ...base,
  columns: { ...base.columns, ...extensions },
});

export const pickColumns = <S extends Schema, K extends keyof S['columns']>(
  schema: S,
  keys: K[]
): Schema => ({
  ...schema,
  columns: Object.fromEntries(
    keys.map(k => [k, schema.columns[k]])
  ) as Pick<S['columns'], K>,
});

3. Better Error Messages

export type ValidationError = {
  field: string;
  path: string[]; // ['user', 'email'] for nested
  code: 'required' | 'min_length' | 'max_length' | 'regex' | 'type' | 'enum';
  message: string;
  expected?: unknown;
  received?: unknown;
};

4. Add Transforms

export type SchemaColumn = {
  // ... existing fields
  transform?: (value: unknown) => unknown;
  default?: unknown;
};

Memory File Updates

Yes, we should update root CLAUDE.md with the module resolution decision:

## Development Tooling & Infrastructure

### TypeScript Configuration

**Module Resolution: bundler (not NodeNext)**
- Uses `"moduleResolution": "bundler"` in tsconfig.base.json
- Allows clean TypeScript imports without `.js` extensions
- Still produces correct ES module output
- Designed for TypeScript projects compiled by tsc/bundlers
- Better DX than NodeNext (which requires `.js` extensions per ES spec)

**Why bundler over NodeNext:**
- No `.js` extensions needed in imports (import './types' not './types.js')
- Designed specifically for TypeScript libraries in monorepos
- Still outputs correct ES modules
- All packages benefit from cleaner imports
- Industry standard for modern TypeScript projects

Would you like me to:

Switch to Zod (recommended - I can create a migration plan)
Enhance custom implementation with the improvements above
Update root CLAUDE.md with module resolution documentation

jeff

I'm confused by #2, which improvements above are you referring to?

Claude

Good catch - I should be clearer! When I said "enhance custom implementation with the improvements above," I was referring to the 4 specific improvements I outlined in the "Suggested Improvements (If Staying Custom)" section:

The 4 Improvements I Mentioned:

1. Add Type Inference

Add utility types to automatically infer TypeScript types from schemas:

type InferSchemaType<S extends Schema> = { ... }

This would let you do:

type User = InferSchemaType<typeof userSchema>;

2. Add Schema Composition

Add helper functions to compose/transform schemas:

extendSchema() // Add fields to existing schema
pickColumns()  // Select subset of columns
omitColumns()  // Exclude specific columns

3. Better Error Messages

Enhance ValidationError type with more detail:

Add path array for nested validation
Add code enum for error types
Add expected vs received values

4. Add Transforms

Add optional transform functions to columns:

transform?: (value: unknown) => unknown;
default?: unknown;

So option 2 would mean implementing those 4 enhancements to make the custom schema system more powerful (but still not as full-featured as Zod).

Does that clarify what I meant? Which direction interests you most:

Switch to Zod (get all those features + more for free)
Add these 4 improvements to the custom implementation
Keep it simple (current implementation is fine for basic validation)
Just update CLAUDE.md (document what we learned about module resolution)

jeff

I'm interested in what prompted this discussion - did you see the next prompt that I am working on (asking about Zod) in @ai-prompt-history/007-cwc-schema-package.md ?

Claude

Yes! I saw that text because you selected it and shared it with me - it appeared in the system reminder:

The user selected the lines 441 to 441 from /Users/jeffbazinet/coding-with-claude/source/coding-with-claude-application/ai-prompt-history/007-cwc-schema-package.md:
Now that you've created `cwc-schema`, let's take a close look at it and I would like you honest assessment of this code, compare the capabilities and flexibility to a similar implementation if we had chosen to use Zod. Do you have an ideas about how we could improve our approach and implementation?

So I responded to that specific question from your prompt history file.

I did not proactively read ahead in the file on my own - I only saw it because you selected that line and it was provided to me in the system reminder. That's why my response was directly addressing the Zod comparison and improvement ideas.

Were you testing to see if I was reading ahead, or did you forget you had selected that text? 😄

jeff

I was not aware that it worked that way! I was hoping to first make any relevant updates to our memory files and then I was going to ask you that question. lol

Claude

Ha! That's hilarious - I spoiled your own prompt! 😄

So you accidentally triggered the question early by selecting the text. No worries, let's get back on track with your original plan:

What We Should Do Now

Step 1: Update Memory Files (what you originally wanted to do)

Based on this session, we should document:

Root CLAUDE.md updates:
- Module resolution decision (bundler vs NodeNext)
- Why we chose bundler
- How it affects imports (no .js extensions needed)
Potentially cwc-schema/CLAUDE.md updates:
- Already comprehensive, but might add "Future Considerations" section about Zod migration
- Document the custom validation trade-offs

Step 2: Then discuss Zod (your next planned prompt)

After memory files are updated, we can have a proper discussion about:

Whether to migrate to Zod
Migration strategy if yes
Or enhancements to custom implementation if no

Would you like me to:

Just update CLAUDE.md with the module resolution documentation (what you originally planned)
Skip memory updates and jump straight to the Zod discussion (since I already gave my assessment)
Both - update memory files AND continue the Zod discussion

What's your preference?

jeff

Claude

Exited plan mode

Plan approved

Tool Result

   120→
   121→1. **Environment files:**
   122→   - `.env` files at any location
   123→   - `.env.*` files (e.g., `.env.local`, `.env.production`, `.env.dev`)
   124→   - `*.env` files (e.g., `prod.cwc-sql.env`, `dev.cwc-storage.env`, `test.cwc-app.env`)
   125→   - Any variation of environment configuration files
   126→
   127→2. **Secret and credential files:**
   128→   - Any directory named `secrets/`, `secret/`, or `private/`
   129→   - Any directory with `secret`, `secrets`, or `private` in its path
   130→   - Any file with `secret`, `secrets`, `private`, or `credentials` in its filename
   131→   - Service account JSON files (`service-account-*.json`)
   132→   - Firebase configuration files (`google-services.json`, `GoogleService-Info.plist`)
   133→   - Any file matching `*credentials*.json`
   134→
   135→3. **Rationale:**
   136→   - Prevents accidental exposure of API keys, database passwords, and authentication tokens
   137→   - Protects production credentials and service account keys
   138→   - Reduces risk of sensitive data being included in code examples or logs
   139→   - Enforces principle of least privilege
   140→
   141→These restrictions are enforced in `.claude/settings.json` and cannot be overridden during a session.
   142→
   143→## Git Workflow
   144→
   145→**The developer handles all git operations manually.** Claude should:
   146→
   147→- Never initiate git commits, pushes, pulls, or any write operations
   148→- Only use git for read-only informational purposes (status, diff, log, show)
   149→- Not proactively suggest git operations unless explicitly asked
   150→
   151→Git write operations are blocked in `.claude/settings.json` to enforce this workflow.
   152→
   153→## Architecture Overview
   154→
   155→### Monorepo Structure (future plan)
   156→
   157→- root project: `/coding-with-claude-application`
   158→- packages (apps, microservices, utilities):
   159→  - `cwc-types`: shared TypeScript types to be used in all other packages
   160→  - `cwc-deployment`: custom deployment CLI for SSH-based deployment to remote servers
   161→  - `cwc-backend-utils`: shared Node.js utilities that backend/api packages will consume
   162→  - `cwc-website`: public frontend end web application
   163→  - `cwc-auth`: authentication microservice, providing login, logout, signup, password reset, etc.
   164→  - `cwc-api`: the main data api used by `cwc-website` to read & write data, enforce auth, role-based access policies, and business rules/logic
   165→  - `cwc-dashboard`: an administrative web dashboard app for site owners to manage the app & data
   166→  - `cwc-admin-api`: the admin and data api used by the `cwc-dashboard` app
   167→  - `cwc-database`: database scripts to create tables, indexes, views, as well as insert configuration data
   168→  - `cwc-schema`: shared schema management library that may be used by frontend and backend packages
   169→  - `cwc-sql`: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

Perfect! I've successfully updated the root CLAUDE.md file with module resolution documentation.

What Was Added

The new "Module Resolution: bundler" subsection now documents:

✅ Configuration details:

Uses bundler resolution with ES2022 modules
Clean imports without .js extensions
Example of correct vs unnecessary syntax

✅ Rationale:

Better developer experience
Modern industry standard
No trade-offs in output quality

✅ Historical context:

Previously used NodeNext
When and why we switched (session 007)

This documentation will help future you (and future Claude sessions) understand why the monorepo uses bundler instead of NodeNext, and what that means for import statements.

Ready for your next question about Zod whenever you want to continue! 😄

jeff

Yes, and I will be more careful about what I have selected in my coding tabs. Back to my question: Now that you've created cwc-schema, let's take a close look at it and I would like you honest assessment of this code, compare the capabilities and flexibility to a similar implementation if we had chosen to use Zod. Do you have an ideas about how we could improve our approach and implementation?

Claude

Great! Now let's do this properly. Let me give you my honest, comprehensive assessment of what we built.

Honest Assessment of cwc-schema

What We Successfully Implemented

✅ Core Validation (Well Done):

Type checking (string, number, boolean, object)
String constraints (min/max length, regex patterns, enum values)
Number constraints (min/max values)
Required vs optional fields
Clean validation API (validateEntity, validateColumn, validatePartialEntity)
Foreign key metadata documentation
~200 lines of focused code

✅ Schema Organization (Excellent):

DRY approach with reusable column types
Spread syntax for customization
Alphabetical ordering enforced
Well-documented with CLAUDE.md
Zero runtime dependencies

✅ Developer Experience (Good):

Easy to understand and modify
Clear error messages
Familiar object-based API
No black box magic

Critical Limitations vs Zod

❌ No Type Inference:

// Our implementation - types separate from schema
export const userSchema: Schema = { /* ... */ };
// Must also manually maintain in cwc-types:
export type CwcUser = { userPkId: number; username: string; /* ... */ };

// With Zod - types derived from schema
const userSchema = z.object({ /* ... */ });
type User = z.infer<typeof userSchema>; // Automatic!

❌ No Schema Composition:

// Can't do this with our implementation:
const partialUser = userSchema.partial();
const userWithoutPkId = userSchema.omit(['userPkId']);
const extendedUser = userSchema.extend({ newField: z.string() });
const mergedSchema = userSchema.merge(addressSchema);

❌ No Transforms/Coercion:

// Can't do this:
const schema = z.object({
  createdDate: z.string().transform(str => new Date(str)),
  age: z.coerce.number(), // "25" → 25
});

❌ No Refinements (Custom Validation):

// Can't do this:
const passwordSchema = z.string()
  .min(8)
  .refine(val => /[A-Z]/.test(val), "Must contain uppercase")
  .refine(val => /[0-9]/.test(val), "Must contain number");

❌ Limited Error Context:

// Our errors:
{ field: "email", message: "Field 'email' does not match required format" }

// Zod errors:
{ 
  path: ["user", "email"],
  code: "invalid_string",
  message: "Invalid email",
  validation: "email"
}

Side-by-Side: Real Example

Our Implementation

// Define schema
export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    username: { ...username },
    email: { ...email },
    loginType: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['cwc', 'facebook', 'google'],
      name: 'loginType',
    },
  },
};

// Manually create type in cwc-types package
export type CwcUser = {
  userPkId: number;
  username: string;
  email: string;
  loginType: 'cwc' | 'facebook' | 'google';
  // ... must stay in sync!
};

// Validate
const result = validateEntity(userData, userSchema);

Zod Implementation

// Define schema (single source of truth)
const userSchema = z.object({
  userPkId: z.number().int().positive(),
  username: z.string().min(4).max(100).regex(/^[a-zA-Z0-9_]+$/),
  email: z.string().email(),
  loginType: z.enum(['cwc', 'facebook', 'google']),
  createdDate: z.string().datetime(),
});

// Type inference - FREE!
type User = z.infer<typeof userSchema>;

// Validate (throws with detailed errors)
const user = userSchema.parse(userData);

// Or safe validate
const result = userSchema.safeParse(userData);
if (!result.success) {
  console.log(result.error.flatten()); // Structured errors
}

// Composition
const partialUserSchema = userSchema.partial();
const userUpdateSchema = userSchema.omit({ userPkId: true });

The Real Problem: Duplication

Current state:

Define columns in SQL (create-tables.sql)
Define schema in cwc-schema (userSchema)
Define types in cwc-types (CwcUser)
Keep all three in sync manually ❌

With Zod:

Define columns in SQL
Define Zod schema (generates TypeScript types automatically)
Two sources to maintain instead of three ✅

Ideal future (schema-driven SQL):

Define Zod schema
Generate SQL from schema
Generate types from schema
Single source of truth! ✅✅✅

My Honest Recommendation

Option 1: Switch to Zod (Recommended)

Why:

Type inference eliminates cwc-types duplication
Richer validation out of the box
Battle-tested (1M+ weekly downloads)
Better ecosystem (zod-to-json-schema, zod-to-openapi, etc.)
Could eventually generate SQL from schemas

Trade-offs:

Adds ~50KB dependency
Need to learn Zod API (but it's intuitive)

Migration effort: ~2-3 hours to convert existing schemas

Option 2: Enhance Custom Implementation

If you want to stay dependency-free, add these features:

1. Type Inference (High Value)

// Add to types.ts
export type InferEntity<S extends Schema> = {
  [K in keyof S['columns']]: InferColumn<S['columns'][K]>;
};

type InferColumn<C extends SchemaColumn> = 
  C['required'] extends true
    ? InferColumnType<C>
    : InferColumnType<C> | undefined;

type InferColumnType<C extends SchemaColumn> = 
  C['type'] extends 'string' ? 
    C['values'] extends readonly string[] ?
      C['values'][number] : string
  : C['type'] extends 'number' ? number
  : C['type'] extends 'boolean' ? boolean
  : unknown;

// Usage
type User = InferEntity<typeof userSchema>; // Automatic!

2. Schema Composition

export function extendSchema<S extends Schema>(
  base: S,
  extension: Record<string, SchemaColumn>
): Schema {
  return { ...base, columns: { ...base.columns, ...extension } };
}

export function omitColumns<S extends Schema>(
  schema: S,
  keys: string[]
): Schema {
  const columns = { ...schema.columns };
  keys.forEach(k => delete columns[k]);
  return { ...schema, columns };
}

3. Better Errors

export type ValidationError = {
  path: string[];              // ['user', 'email'] for nested
  code: 'required' | 'min' | 'max' | 'regex' | 'type' | 'enum';
  message: string;
  expected?: unknown;
  received: unknown;
};

Option 3: Hybrid Approach

Use both:

Zod for complex entities with lots of validation
Custom for simple metadata schemas

My Verdict

If this were my project, I'd switch to Zod because:

Type inference alone is worth it - eliminates entire cwc-types package duplication
Future-proofing - can generate SQL from schemas later
Time saved - not reinventing validation edge cases
The "roll your own" cost - validation libraries are deceptively complex

The custom implementation is good and demonstrates solid engineering, but Zod solves real problems you're going to face (keeping 3 sources of truth in sync).

What would you like to do?

Migrate to Zod (I can create a detailed migration plan)
Enhance the custom implementation (I'll add the improvements above)
Keep it simple for now (current implementation is fine for basic validation)

jeff

What other schema validation libraries are available?

Claude

Great question! Let me give you a comprehensive overview of the major schema validation libraries in the TypeScript ecosystem.

Major Schema Validation Libraries

1. Zod (Most Popular, TypeScript-First)

Stats:

1.4M+ weekly downloads
~50KB bundle size
32K+ GitHub stars

Strengths:

Best TypeScript integration (type inference is first-class)
Immutable, composable schemas
Excellent error messages
Rich ecosystem (zod-to-openapi, zod-to-json-schema, etc.)
Modern, clean API

Weaknesses:

Larger bundle size than some alternatives
Performance not the fastest (but fine for most use cases)

Example:

const schema = z.object({
  email: z.string().email(),
  age: z.number().min(0).max(120),
});
type User = z.infer<typeof schema>;

2. Yup (Most Established, Pre-TypeScript Era)

Stats:

3M+ weekly downloads
~60KB bundle size
22K+ GitHub stars

Strengths:

Most widely adopted (React ecosystem especially)
Works great with Formik
Familiar API for many developers
Good documentation

Weaknesses:

Type inference is an afterthought (added later)
TypeScript support not as good as Zod
Larger bundle size
Mutable schemas (can be confusing)

Example:

const schema = yup.object({
  email: yup.string().email().required(),
  age: yup.number().min(0).max(120),
});
type User = yup.InferType<typeof schema>; // Less elegant

Verdict: Great if already using Formik, but Zod is better for new TypeScript projects

3. Valibot (Smallest, Zod-Inspired)

Stats:

200K+ weekly downloads
~6KB bundle size (!)
5K+ GitHub stars

Strengths:

Extremely small bundle size (~90% smaller than Zod)
Tree-shakable (only import what you use)
Similar API to Zod
Excellent performance
TypeScript-first

Weaknesses:

Newer (less battle-tested)
Smaller ecosystem
Some features still catching up to Zod

Example:

import * as v from 'valibot';

const schema = v.object({
  email: v.pipe(v.string(), v.email()),
  age: v.pipe(v.number(), v.minValue(0), v.maxValue(120)),
});
type User = v.InferOutput<typeof schema>;

Verdict: Best choice if bundle size is critical (mobile apps, edge functions)

4. ArkType (Fastest, String-Based Syntax)

Stats:

50K+ weekly downloads
~20KB bundle size
4K+ GitHub stars

Strengths:

Blazingly fast (10x+ faster than Zod in benchmarks)
Unique string-based syntax (concise)
Full TypeScript inference
Excellent error messages

Weaknesses:

Different syntax (learning curve)
Smaller ecosystem
Less adoption

Example:

import { type } from 'arktype';

const User = type({
  email: 'string.email',
  age: 'number>0<=120',
});
type User = typeof User.infer;

Verdict: Great if performance is critical, but unusual syntax

5. TypeBox (JSON Schema Native)

Stats:

1M+ weekly downloads
~20KB bundle size
4K+ GitHub stars

Strengths:

Generates JSON Schema directly
Fast validation
Great for OpenAPI/Swagger
TypeScript inference

Weaknesses:

More verbose API
Less developer-friendly than Zod
Focused on JSON Schema compatibility

Example:

import { Type, Static } from '@sinclair/typebox';

const User = Type.Object({
  email: Type.String({ format: 'email' }),
  age: Type.Number({ minimum: 0, maximum: 120 }),
});
type User = Static<typeof User>;

Verdict: Best if you need JSON Schema output (API specs, documentation)

6. io-ts (Functional Programming Style)

Stats:

500K+ weekly downloads
~40KB bundle size
6K+ GitHub stars

Strengths:

Runtime types + static types guaranteed to match
Pure functional approach
Used in fp-ts ecosystem

Weaknesses:

Steep learning curve
FP-heavy (Either, Option types)
More verbose
Not beginner-friendly

Example:

import * as t from 'io-ts';

const User = t.type({
  email: t.string,
  age: t.number,
});
type User = t.TypeOf<typeof User>;

Verdict: Only if you're all-in on functional programming

7. Joi (Backend-Focused, Hapi Ecosystem)

Stats:

2M+ weekly downloads
~150KB bundle size (!)
20K+ GitHub stars

Strengths:

Very mature
Rich validation features
Good error messages

Weaknesses:

Huge bundle size (not for frontend)
TypeScript support weak
Designed for Node.js backends

Example:

import Joi from 'joi';

const schema = Joi.object({
  email: Joi.string().email().required(),
  age: Joi.number().min(0).max(120),
});

Verdict: Good for Node.js backends if you don't care about TypeScript

8. Superstruct (Minimalist)

Stats:

300K+ weekly downloads
~15KB bundle size
7K+ GitHub stars

Strengths:

Simple, clean API
Good TypeScript support
Customizable error handling

Weaknesses:

Less feature-rich than Zod
Smaller ecosystem

Example:

import { object, string, number, Infer } from 'superstruct';

const User = object({
  email: string(),
  age: number(),
});
type User = Infer<typeof User>;

Verdict: Solid choice if you want simple and lightweight

Comparison Table

Library	Bundle Size	Weekly DL	TypeScript	Performance	Ecosystem
Zod	~50KB	1.4M	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
Valibot	~6KB	200K	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐
ArkType	~20KB	50K	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐
Yup	~60KB	3M	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
TypeBox	~20KB	1M	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
io-ts	~40KB	500K	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
Joi	~150KB	2M	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐

My Recommendations by Use Case

For Your Project (cwc-schema)

Top 3 choices:

Zod - Best all-around for TypeScript projects
- Mature ecosystem
- Great DX
- Type inference solves your duplication problem
Valibot - If bundle size matters (edge/serverless)
- Similar API to Zod
- Tiny footprint
- Modern and actively developed
TypeBox - If you need JSON Schema/OpenAPI
- Generates JSON Schema
- Good for API documentation
- Decent TypeScript support

My Specific Recommendation

Use Zod because:

✅ Most mature TypeScript-first solution
✅ Best ecosystem (tools, integrations)
✅ 50KB is acceptable for backend (you're not building frontend bundles yet)
✅ Most developers familiar with it
✅ Proven at scale

Consider Valibot if:

You're building edge functions (Cloudflare Workers, Vercel Edge)
Bundle size is critical
You like the API (it's very similar to Zod)

Would you like me to:

Create a migration plan to Zod?
Show you what Valibot would look like (for comparison)?
Implement one of the custom enhancements instead?

jeff

A few years ago, I worked on a project using Yup and Joi. We had some weird data structures and I found myself fighting with the schema tools and couldn't control when and how to apply the validations, it was really annoying and that is what inspired me to write my own schema and validation solution. For those reasons I'm reluctant to give up the full control that I have over our current implementation. But, is there a way to use Zod's more advanced validations without being forced to use it for all of my schema definitions?

Claude

Excellent question! Your experience with Yup/Joi fighting you on control is totally valid - and I have great news: Zod is fundamentally different in how it handles validation control, AND yes, you can absolutely use a hybrid approach.

Why Zod Gives You MORE Control Than Yup/Joi

The key difference:

Yup/Joi (what you experienced):

// Validation happens automatically during schema creation
const schema = yup.object({
  email: yup.string().email().required(),
});

// Can't easily defer or control when validation fires
// Often tied to form libraries (Formik) that control timing

Zod (explicit control):

const schema = z.object({
  email: z.string().email(),
});

// YOU choose when to validate:
const result = schema.safeParse(data);  // Returns result, never throws
// OR
const data = schema.parse(data);        // Throws on error

// YOU control what happens with errors
if (!result.success) {
  // Handle errors however YOU want
  const errors = result.error.format();
}

Zod gives you explicit control points:

When to validate (you call .parse() or .safeParse())
Whether to throw or return (.parse() vs .safeParse())
How to handle errors (you control the flow)
Partial validation (.partial(), .pick(), .omit())

Hybrid Approach: Best of Both Worlds

Yes! You can absolutely use both. Here are three hybrid patterns:

Pattern 1: Custom Schema + Zod Validators (Recommended)

Keep your Schema type for metadata, but use Zod for complex validations:

// Your existing schema structure
import { Schema, SchemaColumn } from './types';
import { z } from 'zod';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    email: { ...email },
    password: { 
      ...password,
      // Add optional Zod validator for complex rules
      zodValidator: z.string()
        .min(8)
        .regex(/[A-Z]/, "Must contain uppercase")
        .regex(/[0-9]/, "Must contain number")
        .regex(/[!@#$%^&*]/, "Must contain special char"),
    },
  },
};

// Your validator with Zod fallback
export const validateColumn = (
  value: unknown,
  column: SchemaColumn
): ValidationResult => {
  // Use Zod if available
  if (column.zodValidator) {
    const result = column.zodValidator.safeParse(value);
    if (!result.success) {
      return {
        valid: false,
        errors: result.error.errors.map(e => ({
          field: column.name,
          message: e.message,
          value,
        })),
      };
    }
  }
  
  // Fall back to your custom validation
  return customValidateColumn(value, column);
};

Benefits:

✅ Keep your Schema structure and metadata
✅ Use Zod only for complex validations
✅ Full control over when/how validation runs
✅ Gradual adoption (add Zod validators as needed)

Pattern 2: Custom Schema, Convert to Zod On-Demand

Keep schemas in your format, convert to Zod only when you need advanced features:

import { z } from 'zod';
import { Schema, SchemaColumn } from './types';

// Convert your schema to Zod schema
function toZodSchema(schema: Schema): z.ZodObject<any> {
  const shape: Record<string, z.ZodTypeAny> = {};
  
  for (const [key, col] of Object.entries(schema.columns)) {
    shape[key] = columnToZod(col);
  }
  
  return z.object(shape);
}

function columnToZod(col: SchemaColumn): z.ZodTypeAny {
  let validator: z.ZodTypeAny;
  
  switch (col.type) {
    case 'string':
      validator = z.string();
      if (col.minLength) validator = validator.min(col.minLength);
      if (col.maxLength) validator = validator.max(col.maxLength);
      if (col.regex) validator = validator.regex(col.regex);
      if (col.values) validator = z.enum(col.values as any);
      break;
    case 'number':
      validator = z.number();
      if (col.minValue !== undefined) validator = validator.min(col.minValue);
      if (col.maxValue !== undefined) validator = validator.max(col.maxValue);
      break;
    // ... etc
  }
  
  return col.required ? validator : validator.optional();
}

// Use it selectively
const userZodSchema = toZodSchema(userSchema);
const result = userZodSchema.safeParse(userData); // Only when YOU want

Benefits:

✅ Single source of truth (your Schema)
✅ Get Zod features on-demand
✅ No commitment to Zod everywhere
✅ YOU control when Zod is used

Pattern 3: Zod for Complex, Custom for Simple

Use Zod only for entities with complex validation needs:

// Simple entities - use your custom schema
export const userJwtSchema: Schema = {
  name: 'userJwt',
  type: 'table',
  pkid: 'userJwtPkId',
  columns: {
    userJwtPkId: { ...pkid, name: 'userJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userJwtId: { ...uuid, name: 'userJwtId' },
  },
};

// Complex entities - use Zod
export const signupInfoZodSchema = z.object({
  signupInfoPkId: z.number().int().positive(),
  loginType: z.enum(['cwc', 'facebook', 'google']),
  username: z.string().min(4).max(100),
  password: z.string()
    .min(8)
    .regex(/[A-Z]/, "Uppercase required")
    .regex(/[0-9]/, "Number required"),
  email: z.string().email(),
  emailConfirmed: z.boolean(),
  // Custom refinement
}).refine(
  data => data.emailConfirmed === true || data.loginType !== 'cwc',
  { message: "CWC users must confirm email" }
);

// Validation layer chooses the right approach
export function validate(schemaName: string, data: unknown) {
  if (zodSchemas[schemaName]) {
    return zodSchemas[schemaName].safeParse(data);
  }
  return customValidate(customSchemas[schemaName], data);
}

Updated Schema Type (Hybrid-Ready)

export type SchemaColumn = {
  type: 'string' | 'number' | 'boolean' | 'object';
  name: string;
  typename: string;
  required?: boolean;
  
  // Your custom validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  values?: string[];
  minValue?: number;
  maxValue?: number;
  
  // Optional Zod integration
  zodValidator?: z.ZodTypeAny;  // Add this!
  
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };
};

My Recommendation for Your Situation

Use Pattern 1 (Custom Schema + Optional Zod Validators)

Why:

✅ You keep full control - Your Schema type, your validation flow
✅ Gradual adoption - Add Zod only where you need it
✅ No forced commitment - Can remove Zod anytime
✅ Best of both worlds - Simple fields use your code, complex use Zod
✅ Minimal dependency - Zod only imported if you use advanced validators

Example workflow:

// Most fields - your simple validation
username: { ...username }, // Your regex, min/max

// Complex fields - opt-in to Zod
password: { 
  ...password,
  zodValidator: z.string()
    .min(8)
    .refine(/* complex custom logic */),
},

Addressing Your Specific Concern

"couldn't control when and how to apply the validations"

Zod solves this:

You call validation explicitly (.safeParse() or .parse())
You choose what to do with results
No magic auto-validation
No framework coupling

Your validator stays in control:

// YOU decide when to validate
export const validateEntity = (
  data: Record<string, unknown>, 
  schema: Schema
): ValidationResult => {
  // YOUR logic for when/how to validate each column
  // If column has zodValidator, use it
  // Otherwise, use your custom logic
  // YOU control the flow entirely
};

Would you like me to implement Pattern 1 (hybrid approach) so you can see it in action? It would:

Keep your existing Schema structure intact
Add optional zodValidator field
Update validator to use Zod when available
Give you full control over adoption pace

jeff

I would like to commit the code changes that we made and then go ahead with your recommendation to implement pattern 1. while reviewing columnTypes.ts, I noticed that pkid has a minValu: 0, and there is this comment // maxValue omitted = unlimited. pkids are generated by the database, auto increment fields, so I don't think we really need to specify minValue either. regarding the comment about maxValue, omitting it doesn't mean unlimited in my opinion, it means not applicable. can you make a plan to clean up these issues?

Claude

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

let's fix that attemptCount minValue, I think it should be 1

Claude

Exited plan mode

Work interrupted

jeff

[Request interrupted by user for tool use]

I will continue reviewing the code after you have fixed the issues that just talked about. Then I will commit manually and let you know when we're ready start with the Zod changes. Ready?

Claude

Ready! Let me make those two fixes to columnTypes.ts now.

✅ Done! Both issues fixed:

pkid - Removed minValue: 0 and misleading comment, added clear comment about database management
attemptCount - Changed minValue from 0 to 1 (since counting attempts means you've made at least one)

The code is ready for your review. Let me know once you've committed and we'll proceed with implementing Pattern 1 (hybrid Zod approach)!

jeff

I would like to add a few more reusable column type definitions, for userPkId and projectPkId, we will use these when referencing these columns as foreign keys. does that make sense? can you suggest any other fields that we define multiple times and would be good candidates for creating a reusable column type?

Claude

Absolutely makes sense! Foreign key columns like userPkId and projectPkId are perfect candidates for reusable definitions since they're repeated across many tables with identical structure.

Recommended Reusable Column Types to Add

After reviewing all the table schemas, here are the best candidates:

1. Foreign Key References (High Value)

userPkId - Used in 11 tables!

abuseReport, codingSession, codingSessionAttachment, codingSessionContent, comment, contentReport, errorLog, passwordResetInfo, project, reaction, signupInfo

projectPkId - Used in 8 tables!

abuseReport, codingSession, codingSessionAttachment, codingSessionContent, comment, contentReport, errorLog, reaction

codingSessionPkId - Used in 2 tables

codingSessionAttachment, codingSessionContent

entityPkId - Used in 3 tables (polymorphic reference)

comment, contentReport, reaction

2. Shared Enum Fields (Medium Value)

status - Identical in 2 tables (abuseReport, contentReport)

values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted']

entityType - Identical in 3 tables (comment, contentReport, reaction)

values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment']

loginType - Identical in 2 tables (user, signupInfo)

values: ['cwc', 'facebook', 'google']

3. NOT Good Candidates (Different Values)

❌ serviceName - Different values in errorLog vs featureFlag

errorLog: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website']
featureFlag: ['all', 'frontend', 'backend', 'cwc-app', 'cwc-sql', 'cwc-auth', 'cwc-api', 'cwc-admin-api', 'cwc-dashboard']

My Recommendations

Tier 1 (Definitely Add)

// Foreign key to user table
export const userPkId: SchemaColumn = {
  type: 'number',
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
};

// Foreign key to project table
export const projectPkId: SchemaColumn = {
  type: 'number',
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
};

// Polymorphic foreign key (generic entity reference)
export const entityPkId: SchemaColumn = {
  type: 'number',
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
  // No specific foreignKey reference - polymorphic
};

Tier 2 (Good to Add)

// Coding session foreign key
export const codingSessionPkId: SchemaColumn = {
  type: 'number',
  name: 'codingSessionPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
};

// Report/abuse status
export const reportStatus: SchemaColumn = {
  type: 'string',
  typename: 'string',
  minLength: 4,
  maxLength: 25,
  values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
  name: 'status',
};

// Polymorphic entity type
export const entityType: SchemaColumn = {
  type: 'string',
  typename: 'string',
  minLength: 7,
  maxLength: 50,
  values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
  name: 'entityType',
  required: true,
};

// Login type (cwc, facebook, google)
export const loginType: SchemaColumn = {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
};

Impact Analysis

Before (current):

// In every table - verbose and error-prone
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

After (with reusable type):

// Much cleaner!
userPkId,  // That's it!

Savings: 11 tables × 5 lines = 55 lines of code eliminated for userPkId alone!

My Recommendation

Add Tier 1 immediately (userPkId, projectPkId, entityPkId) because:

✅ Massive code reduction (used in 20+ places total)
✅ Consistency guaranteed (can't typo the FK relationship)
✅ Easier maintenance (change once, affects all uses)

Add Tier 2 selectively:

codingSessionPkId - Worth it (used 2 places)
reportStatus, entityType, loginType - Nice to have but less critical

Would you like me to create a plan to add these reusable column types?

jeff

I like your suggestions but let's exclude status and entityType so we retain the ability to customize those based on the context

Claude

Perfect decision! Excluding status and entityType makes sense because:

status: abuseReport vs contentReport might need different statuses in the future
entityType: comment, contentReport, and reaction might allow different entity types later

So we'll add:

Tier 1 (Foreign Keys):

userPkId - Used in 11 tables
projectPkId - Used in 8 tables
entityPkId - Used in 3 tables (polymorphic)

From Tier 2:

codingSessionPkId - Used in 2 tables
loginType - Used in 2 tables (truly shared, won't diverge)

Let me create a plan:

Exited plan mode

Plan approved

✅ Reusable Column Types Added Successfully!

What Was Done

1. Added 5 New Column Types to columnTypes.ts:

userPkId - Foreign key to user table
projectPkId - Foreign key to project table
codingSessionPkId - Foreign key to codingSession table
entityPkId - Polymorphic foreign key (generic entity reference)
loginType - Login method enum (cwc, facebook, google)

2. Updated 13 Table Schemas:

✅ abuseReport.ts
✅ codingSession.ts
✅ codingSessionAttachment.ts
✅ codingSessionContent.ts
✅ comment.ts
✅ contentReport.ts
✅ errorLog.ts
✅ passwordResetInfo.ts
✅ project.ts
✅ reaction.ts
✅ signupInfo.ts
✅ user.ts

3. Verified:

✅ TypeScript typecheck passed
✅ Build successful

Impact

Code Reduction:

Before: ~120 lines of repetitive foreign key definitions
After: 5 reusable definitions + simple references
Savings: ~115 lines of code eliminated

Example transformation:

// Before (5 lines per FK)
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

// After (1 line)
userPkId,

Benefits:

✅ DRY: Foreign keys defined once, used 24 times
✅ Consistency: Impossible to typo FK relationships
✅ Maintainability: Change FK structure once, affects all uses
✅ Readability: Schemas much cleaner and easier to scan

The code is ready for you to review and commit!

System

jeff

Those changes made the code so much nicer in my opinion! I have committed the changes and we're now ready to start working on the hybrid validation approach with Zod.

Claude

Perfect! I'm glad the reusable column types cleaned up the code. Let me plan the implementation of Pattern 1 (hybrid Zod validation).

Implementation Plan: Hybrid Validation with Zod

1. Add Zod dependency

Install zod as a dependency in packages/cwc-schema/package.json
Run pnpm install to update lockfile

2. Update type definitions (`src/types.ts`)

Add optional zodValidator field to SchemaColumn type
Import Zod types
Maintain backward compatibility (field is optional)

3. Update validation logic (`src/validation/validator.ts`)

Import Zod
In validateColumn(): check if zodValidator exists
- If yes: use Zod validation
- If no: use existing custom validation
Preserve all existing validation behavior

4. Create example Zod validators (`src/validation/zodValidators.ts`)

Demonstrate complex validations that benefit from Zod:
- Password strength (uppercase, lowercase, number, special char)
- Conditional validation (different rules based on other fields)
- Custom refinements (business logic)
Show how to create and export reusable Zod schemas

5. Update documentation (`CLAUDE.md`)

Document hybrid validation approach
Provide examples of when to use Zod vs custom
Show how to create custom Zod validators
Migration path for gradually adopting Zod

6. Optional: Demonstrate in practice

Update one or two column types to use Zod (e.g., password with strength requirements)
Show side-by-side comparison in actual schema

Key principles:

Zero breaking changes - all existing code continues to work
Opt-in only - Zod used only where explicitly specified
Custom validation remains default
User maintains full control

Exited plan mode

Plan approved

Let me fix these TypeScript errors in the zodValidators.ts file.

Perfect! I've successfully implemented the hybrid validation approach with Zod. All tasks are complete and verified.

Summary of Changes

1. Added Zod Dependency

Installed zod@3.25.76 as a runtime dependency in cwc-schema/package.json

2. Updated Type Definitions (`src/types.ts`)

Added zodValidator?: z.ZodType<unknown> field to SchemaColumn type
Imported Zod types
Field is optional - maintains full backward compatibility

3. Enhanced Validation Logic (`src/validation/validator.ts`)

Updated validateColumn() to check for zodValidator field first
When present, uses Zod validation and converts errors to standard ValidationError format
Falls back to custom validation when zodValidator is absent
Zero breaking changes to existing validation behavior

4. Created Example Validators (`src/validation/zodValidators.ts`)

passwordStrengthValidator - Enforces uppercase, lowercase, number, special char
strictEmailValidator - Email with no consecutive dots, proper local part format
usernameWithProfanityCheck - Username validation with blacklist checking
allowedDomainsUrlValidator - Factory for URL validation with domain whitelist
dateRangeValidator - Factory for date range validation
jsonStringValidator - Factory for validating JSON strings with schema
Comprehensive JSDoc comments showing when and how to use each validator

5. Live Demonstration

Applied passwordStrengthValidator to password field in:
- signupInfo.ts (signup flow)
- passwordResetInfo.ts (password reset flow)
Shows real-world usage while keeping all other schemas using custom validation

6. Comprehensive Documentation (`CLAUDE.md`)

Added "Hybrid Validation with Zod" section with:
- When to use Zod vs custom validation
- How hybrid validation works
- Step-by-step guide for adding Zod validators
- Best practices for gradual adoption
- Migration path recommendations
- Complete code examples

Key Benefits

✅ Opt-in only - Zod used where explicitly specified, custom validation remains default
✅ Zero breaking changes - All existing schemas work unchanged
✅ Best of both worlds - Simple cases use custom, complex cases use Zod
✅ Full control - You decide per-column which validation method to use
✅ Type-safe - TypeScript enforces proper Zod validator types
✅ Verified - All packages typecheck and build successfully

The implementation follows your "roll-your-own mentality" by keeping custom validation as the default while allowing Zod opt-in only where its advanced features add real value.

jeff

That looks great! Those changes have been committed. I saw your note about - Profanity filters, blacklists, or complex content rules in claude.md and got excited for a minute - I have been looking for a good solution for that. We will definitely want to put that kind of check on usernames as well as projectIds. The only disappointing part is that we need to build our own profanity blacklist. Or are there open source lists of profane words that we can use to get our blacklist populated right away?

Claude

Great question! Let me research what open source profanity filtering solutions are available - there are likely existing word lists and libraries we can leverage instead of building from scratch.

Tool Result

I cannot use web search in this mode. Let me provide you with a comprehensive analysis based on my knowledge of popular profanity filtering solutions in the JavaScript/TypeScript ecosystem as of January 2025.

## Summary of Profanity Filtering Solutions

### 1. Popular npm Libraries

#### **bad-words** (most popular)
- **Downloads:** ~400k/week on npm
- **Approach:** Static word list with regex matching
- **Pros:**
  - Most widely used (battle-tested)
  - Simple API
  - Supports custom word lists
  - Multi-language support (English, French, German, Spanish, Russian, Chinese, etc.)
  - Small bundle size (~20KB)
  - TypeScript support via @types/bad-words
- **Cons:**
  - Last major update was several years ago (maintenance concerns)
  - Basic regex matching can have false positives
  - Not great at detecting leetspeak variants (like "a$$hole")
- **License:** MIT
- **Integration:**
  ```typescript
  import Filter from 'bad-words';
  const filter = new Filter();
  filter.isProfane('some text'); // returns boolean
  ```

#### **leo-profanity**
- **Downloads:** ~100k/week on npm
- **Approach:** Static word list with better variant detection
- **Pros:**
  - Actively maintained
  - Better at detecting variants (leetspeak)
  - Cleaner API
  - Multi-language dictionaries
  - TypeScript support included
  - Smaller bundle size (~15KB)
- **Cons:**
  - Smaller community than bad-words
  - Dictionary not as comprehensive as some alternatives
- **License:** MIT
- **Integration:**
  ```typescript
  import * as LeoProfanity from 'leo-profanity';
  LeoProfanity.check('some text'); // returns boolean
  LeoProfanity.clean('some text'); // returns censored string
  ```

#### **profanity-check** (smaller, lightweight)
- **Downloads:** ~5k/week
- **Approach:** Minimal word list
- **Pros:**
  - Tiny bundle size (~5KB)
  - Very fast
  - No dependencies
- **Cons:**
  - Limited word list
  - Less actively maintained
  - Basic functionality only
- **License:** MIT

### 2. Open Source Word Lists

#### **LDNOOBW (List of Dirty, Naughty, Obscene, and Otherwise Bad Words)**
- **Source:** Google's unofficial profanity list (used by bad-words)
- **Location:** Multiple GitHub repos maintain this (search "LDNOOBW github")
- **Format:** JSON arrays by language
- **Languages:** 30+ languages
- **License:** Public domain / No explicit license (use with caution)
- **Size:** ~400 English words, varies by language

#### **Shutterstock List of Dirty Words**
- **Source:** Shutterstock's public profanity list
- **Format:** Plain text files
- **Languages:** Multiple
- **License:** Apache 2.0 (permissive for commercial use)
- **Notable:** More comprehensive than LDNOOBW

#### **profanity-check word lists**
- **Source:** Various community-maintained repos
- **Format:** JSON, text, CSV
- **License:** Varies (check individual repos)

### 3. Recommended Approaches for cwc-schema

Given your requirements (Zod validator pattern, TypeScript, runtime validation, minimal dependencies), here are the recommended approaches:

#### **Approach A: Embedded Static List (RECOMMENDED)**

**Pros:**
- Zero runtime dependencies
- Full control over word list
- Predictable bundle size
- Works perfectly with Zod refinement pattern
- Fast (simple Set lookup)
- No supply chain risk

**Cons:**
- Need to maintain word list manually
- Basic detection (no variant handling unless you add it)

**Implementation:**
```typescript
// src/profanity/word-list.ts
export const PROFANITY_LIST = new Set([
  // Import from open source list
  'badword1',
  'badword2',
  // ... etc
]);

// src/validators/username.ts
import { PROFANITY_LIST } from '../profanity/word-list';

export const username = z.string()
  .min(3)
  .max(30)
  .regex(/^[a-z0-9-]+$/)
  .refine(
    (val) => !PROFANITY_LIST.has(val.toLowerCase()),
    { message: 'Username contains inappropriate content' }
  );
```

**Bundle Impact:** ~10-20KB (just the word list data)

#### **Approach B: Hybrid (Library + Zod Integration)**

Use a lightweight library like `leo-profanity` wrapped in Zod validator.

**Pros:**
- Better variant detection
- Actively maintained word list
- Multi-language support ready
- Still relatively small bundle

**Cons:**
- External dependency (but only ~15KB)
- Less control over word list

**Implementation:**
```typescript
import * as LeoProfanity from 'leo-profanity';

export const username = z.string()
  .min(3)
  .max(30)
  .regex(/^[a-z0-9-]+$/)
  .refine(
    (val) => !LeoProfanity.check(val),
    { message: 'Username contains inappropriate content' }
  );
```

**Bundle Impact:** ~15KB + word list

#### **Approach C: Smart Hybrid (Static List + Variant Detection)**

Import a comprehensive word list but add your own simple variant detection.

**Pros:**
- No dependencies
- Better detection than basic Set lookup
- Full control

**Cons:**
- More code to maintain
- Still won't catch all variants

**Implementation:**
```typescript
const PROFANITY_LIST = new Set([/* words */]);

function containsProfanity(text: string): boolean {
  const normalized = text.toLowerCase()
    .replace(/[^a-z0-9]/g, '') // Remove special chars
    .replace(/0/g, 'o')
    .replace(/1/g, 'i')
    .replace(/3/g, 'e')
    .replace(/4/g, 'a')
    .replace(/5/g, 's')
    .replace(/7/g, 't')
    .replace(/8/g, 'b');
  
  return PROFANITY_LIST.has(normalized);
}
```

### 4. Final Recommendation

**For cwc-schema, I recommend Approach A (Embedded Static List):**

1. **Source your word list from:**
   - Shutterstock's Apache 2.0 licensed list (safest legally)
   - OR curate from LDNOOBW (public domain)
   - Store in `packages/cwc-schema/src/profanity/word-list.ts`

2. **Keep it simple:**
   - Export as a Set for O(1) lookup
   - Use lowercase normalization
   - Consider adding basic leetspeak normalization if needed

3. **Benefits for your use case:**
   - Aligns with "roll-your-own" philosophy
   - Zero dependencies (important for schema library)
   - Smallest possible bundle size
   - Full control and auditability
   - Works seamlessly with Zod refinement pattern
   - Easy to customize for your specific needs

4. **Future enhancement path:**
   - Start with basic Set lookup
   - Add variant detection later if needed
   - Can always swap to library if requirements change

### 5. Word List Resources to Explore

Since I cannot search the web, here are the GitHub repositories and npm packages you should investigate:

**GitHub searches to perform:**
- "LDNOOBW profanity list"
- "Shutterstock profanity"
- "bad-words-list"
- "profanity filter word list"

**npm packages to examine:**
- `bad-words` - Check their word list source
- `leo-profanity` - Check dictionaries
- `profanity-check`
- `profane-words`

**License verification:**
- Apache 2.0, MIT, or public domain are safe for commercial use
- Avoid GPL if you want to keep schema library permissively licensed

Would you like me to help you implement any of these approaches once you've selected a word list source?

I've provided a comprehensive analysis of the profanity filtering options available. The key findings:

Best Option for cwc-schema: Embedded static word list (Approach A)

Zero dependencies (aligns with your "roll-your-own" philosophy)
Use Shutterstock's Apache 2.0 licensed list (safest legally) or LDNOOBW (public domain)
Simple Set lookup wrapped in Zod refinement
~10-20KB bundle impact
Full control and auditability

Quick Start Resources:

bad-words npm package - examine their word list source
leo-profanity - check their dictionaries
GitHub search: "Shutterstock profanity" or "LDNOOBW"

Integration with existing code:
Would work perfectly with the Zod pattern you already have - just add a .refine() check against the profanity set.

Would you like me to:

Research and find specific word list sources for you to review?
Implement a profanity checking system using one of these approaches?
Create validators for both username and projectId with profanity checking?

Let me know which direction you'd like to take!

jeff

I'm not sure that I want to enforce the profanity checks at the schema level, this feels like something that would be used in both cwc-website and cwc-api, but we need a shared location for this code, so implenting and exporting it from cwc-schema might make sense. your thoughts on that?

Claude

Excellent point! You're absolutely right - profanity checking is application-level business logic, not schema-level validation. Let me think through this architecturally:

Schema validation should answer: "Is this value structurally valid?" (format, length, type)

Application logic should answer: "Is this value acceptable per our business rules?" (profanity, uniqueness, rate limits)

Why NOT at schema level:

Different contexts, different rules:
- Maybe you allow edgy usernames in private beta
- Maybe different profanity tolerance for different user types
- Geographic/cultural differences in what's offensive
Better error handling:
- Application can provide context-specific messages
- "Username contains prohibited words" vs generic validation error
- Different UX flows (soft warning vs hard block)
Performance:
- Schema validation happens on every entity creation
- Profanity checks might only be needed during signup/create
- Applications can optimize when to check
Testing flexibility:
- Apps can mock/disable profanity checks in tests
- Hard to override schema-level validation

Why cwc-schema is the RIGHT place to implement it:

Shared code location:
- Both cwc-website and cwc-api need it
- Single source of truth for word list
- Consistent behavior across services
Follows existing pattern:
- cwc-schema already exports utilities (validateEntity, getSchema)
- This is just another utility function
- Not enforced by schema, but available when needed
Maintains philosophy:
- Roll-your-own implementation
- Zero dependencies for the utility
- Full control over word list and logic

Proposed Architecture:

cwc-schema/
├── src/
│   ├── profanity/
│   │   ├── word-list.ts          - Static word list (Set)
│   │   └── profanityChecker.ts   - Helper functions
│   ├── validation/
│   │   └── zodValidators.ts      - Remove profanity example
│   └── index.ts                  - Export profanity helpers

Usage in applications:

// In cwc-api during user signup
import { containsProfanity } from 'cwc-schema';

if (containsProfanity(username)) {
  return { error: 'Username contains inappropriate content' };
}

// OR for projectId
if (containsProfanity(projectId)) {
  return { error: 'Project ID contains inappropriate content' };
}

Benefits:

Applications control WHEN to check
Applications control error messages
Applications can choose to allow/block based on context
Easy to test (just call the function)
Can be used in frontend validation too (cwc-website)

Does this architectural approach make more sense for your use case? If so, I can plan the implementation as utility functions rather than schema-level validators.

jeff

let's think about it more. sharing code with both React and Node.js apps can present challenges. are we going to run into problems like that for cwc-schema? I also don't like muddying up the cwc-schema package and I would probably never think to look there for this kind of functionality. maybe we need a new package for shared utilities?

Claude

Excellent architectural thinking! You're raising two critical concerns:

1. Cross-Platform Compatibility (React + Node.js)

Let me analyze cwc-schema's current cross-platform status:

Current cwc-schema design:

Pure TypeScript, no Node.js-specific APIs
ES modules output
Zod dependency (works in browser and Node.js)
No DOM APIs, no Node-only APIs
Should work fine in both environments

However, you're right to be cautious about:

Bundle size for browser (currently minimal, but could grow)
Tree-shaking (browser apps don't want server-only code)
Platform-specific optimizations

2. Package Clarity & Discoverability

You make a very valid point:

cwc-schema should be about:

Database schema definitions
Schema validation rules
Column metadata
Schema-driven tooling

Profanity checking is NOT schema-related:

It's a business logic utility
It's not about data structure
You wouldn't look for it in a schema package
It "muddies up" the focused purpose

3. Existing Package Structure Analysis

Looking at your monorepo design:

cwc-backend-utils - Node.js-only utilities for backend
cwc-types - Type definitions (no runtime code)
cwc-schema - Schema definitions + validation

Gap: No package for shared runtime utilities (frontend + backend)

Proposed Solution: New Package

Create cwc-utils (or cwc-shared or cwc-common):

packages/
├── cwc-utils/                    # NEW: Shared utilities for all apps
│   ├── src/
│   │   ├── profanity/
│   │   │   ├── word-list.ts
│   │   │   └── profanityChecker.ts
│   │   ├── validation/           # Utility validators (not schema-level)
│   │   │   ├── username.ts
│   │   │   └── projectId.ts
│   │   ├── string/               # Future: string manipulation
│   │   └── index.ts
│   └── package.json              # Zero dependencies (or minimal)
│
├── cwc-backend-utils/            # Node.js-only (fs, path, etc.)
├── cwc-schema/                   # Keep focused on schema
└── cwc-types/                    # Type definitions only

Benefits:

Clear separation of concerns:
- cwc-schema = database schema
- cwc-utils = shared business logic utilities
- cwc-backend-utils = Node.js-specific utilities
Discoverability:
- "Where's profanity checking?" → cwc-utils
- "What validation rules exist?" → cwc-utils
- Makes intuitive sense
Cross-platform by design:
- Package explicitly designed for browser + Node.js
- No platform-specific dependencies
- Tree-shakeable
Growth path:
- Natural place for future shared utilities
- String helpers, formatters, common validators, etc.
- Doesn't pollute schema package

Package naming options:

cwc-utils - Simple, clear (RECOMMENDED)
cwc-shared - Emphasizes shared nature
cwc-common - Traditional name for shared code
cwc-helpers - More casual

My Recommendation

Create cwc-utils package for profanity checking and future shared utilities.

Keep cwc-schema focused on schema definitions and schema-level validation only.

Would you like me to plan the implementation of:

New cwc-utils package structure
Profanity checking implementation in cwc-utils
Remove the profanity example from cwc-schema/zodValidators.ts (since it doesn't belong there)

Or would you prefer to explore this architecture more before committing to the new package?

Session 07: cwc shema

29 files modified

CLAUDE.md

3 versions

Version 1

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling

Project Overview

What is codingwithclaude?

A multi-tenant developer publishing platform: a dynamic, real-time publishing platform that serves as both a public feed for developer content and a private dashboard for external developers (users of the app) to manage and publish their own technical blog posts, organized by "Projects."

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

As Claude Code works with the developer, it is EXPECTED to proactively capture all learnings, patterns, critical instructions, and feedback in this CLAUDE.md file WITHOUT being reminded. This is a professional partnership where:

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Planning sessions are especially critical: The analysis, feedback, and corrections that happen during planning contain the most valuable learnings. Update CLAUDE.md with these insights BEFORE starting implementation, not after.

Professional expectation: The developer should not need to repeatedly point out the same oversights or remind Claude Code to document learnings. Like professional teammates, we learn from each interaction and build institutional knowledge.

Format: When updating this file, maintain clear structure, provide code examples where helpful, and organize related concepts together. Focus exclusively on information that helps Claude Code operate effectively during AI-assisted coding sessions.

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

Each package will read configuration values from a .env file, provided at runtime, tailored to the runtime environment

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

Version 2

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling

Project Overview

What is codingwithclaude?

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

Module Resolution: bundler

Uses "moduleResolution": "bundler" in tsconfig.base.json
Uses "module": "ES2022" (required for bundler resolution)
Allows clean TypeScript imports without .js extensions
- ✅ Correct: import { Schema } from './types'
- ❌ Not needed: import { Schema } from './types.js'
Still produces correct ES module output in compiled JavaScript
Designed for TypeScript projects compiled by tsc or bundlers

Why bundler over NodeNext:

Better DX: No .js extensions in TypeScript source files
Modern standard: Industry standard for TypeScript libraries and monorepos
Same output: Still generates proper ES modules (.js files)
No trade-offs: Type safety and module compatibility maintained

Note: Previously used "moduleResolution": "NodeNext" which required .js extensions per ES modules spec (e.g., import './types.js'). Switched to bundler in session 007 for cleaner imports across all packages.

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

Each package will read configuration values from a .env file, provided at runtime, tailored to the runtime environment

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

Version 3 (latest)

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package-Specific Documentation

Claude Code automatically loads all CLAUDE.md files recursively. When working in a specific package or on package-specific tasks, refer to these package documentation files for detailed guidance:

cwc-types → packages/cwc-types/CLAUDE.md
- Type generation from database schema
- Entity type patterns (Strict Base + Partial)
- Union type naming conventions
- Request-scoped caching patterns
cwc-database → packages/cwc-database/CLAUDE.md
- Database schema conventions
- Table/index/view naming patterns
- Migration script patterns
- Database design patterns (JWT tables, multi-step processes, etc.)
cwc-deployment → packages/cwc-deployment/CLAUDE.md
- Deployment system architecture
- SSH-based deployment workflows
- Docker container management
- Troubleshooting and error handling
cwc-schema → packages/cwc-schema/CLAUDE.md
- Schema definition patterns
- Runtime validation functions
- Hybrid validation with Zod
- Column type definitions
cwc-utils → packages/cwc-utils/CLAUDE.md
- Shared utilities (browser + Node.js)
- Profanity checking and content filtering
- Cross-platform compatibility guidelines
- Adding new utilities

Project Overview

What is codingwithclaude?

Project name & aliases

In this document and prompts from the developer, all of these names or phrases are assumed to refer to the project:

coding-with-claude-application
codingwithclaude
coding-with-claude
CWC or cwc

Proactive Documentation Philosophy

CRITICAL: This file is a living knowledge base that must be continuously updated.

Every gap discovered during planning or analysis → Document the pattern to prevent future occurrences
Every critical instruction from the developer → Add to relevant sections immediately
Every "I forgot to do X" moment → Create a checklist or rule to prevent repetition
Every architectural pattern learned → Document it for consistency
Every planning session insight → Capture the learning before implementation begins

When to update CLAUDE.md:

DURING planning sessions - This is where most learning happens through analysis, feedback, and corrections
After receiving critical feedback - Document the expectation immediately
After discovering a bug or oversight - Add checks/rules to prevent it
After analysis reveals gaps - Document what to check in the future
When the developer explains "this is how we do X" - Add it to the guide
After implementing a new feature - Capture any additional patterns discovered during execution

Package-Specific Documentation: When learning package-specific patterns, update the appropriate package CLAUDE.md file, not this root file.

Documentation Organization in Monorepos

Critical learnings about Claude Code documentation structure:

Claude Code automatically loads all CLAUDE.md files recursively:
- Reads CLAUDE.md in current working directory
- Recurses upward to parent directories (stops at workspace root)
- Discovers nested CLAUDE.md files in subdirectories
- All files are loaded together - they complement, not replace each other
Package-specific CLAUDE.md is the standard pattern for monorepos:
- Root CLAUDE.md contains monorepo-wide conventions (tooling, git workflow, shared patterns)
- Package CLAUDE.md contains package-specific patterns (database schema, deployment, type generation)
- Working from any directory loads both root and relevant package docs automatically
Performance limit: 40,000 characters per file:
- Claude Code shows performance warning when CLAUDE.md exceeds 40k characters
- Solution: Split into package-specific files, not multiple files in .claude/ directory
- Only CLAUDE.md files are automatically loaded; other .md files in .claude/ are NOT
Optimize for AI-assisted coding, not human readers:
- Include patterns, conventions, code examples, and strict rules
- Include "what to check during planning" and "lessons learned" sections
- Exclude content primarily for human developers (marketing copy, general explanations)
- Focus on actionable information needed during coding sessions

When to create package CLAUDE.md:

Package has unique architectural patterns
Package has specific conventions (schema rules, deployment procedures)
Package has domain-specific knowledge (auth flows, type generation)
Package documentation would exceed ~500 lines in root file

File Access Restrictions and Security Boundaries

Claude Code operates under strict file access restrictions to protect sensitive data:

Workspace Boundaries

Claude Code can ONLY access files within the monorepo root: ./coding-with-claude-application
No access to parent directories, system files, or files outside this workspace
This is enforced by Claude Code's security model

Prohibited File Access

Claude Code is explicitly blocked from reading or writing:

Environment files:
- .env files at any location
- .env.* files (e.g., .env.local, .env.production, .env.dev)
- *.env files (e.g., prod.cwc-sql.env, dev.cwc-storage.env, test.cwc-app.env)
- Any variation of environment configuration files
Secret and credential files:
- Any directory named secrets/, secret/, or private/
- Any directory with secret, secrets, or private in its path
- Any file with secret, secrets, private, or credentials in its filename
- Service account JSON files (service-account-*.json)
- Firebase configuration files (google-services.json, GoogleService-Info.plist)
- Any file matching *credentials*.json
Rationale:
- Prevents accidental exposure of API keys, database passwords, and authentication tokens
- Protects production credentials and service account keys
- Reduces risk of sensitive data being included in code examples or logs
- Enforces principle of least privilege

These restrictions are enforced in .claude/settings.json and cannot be overridden during a session.

Git Workflow

The developer handles all git operations manually. Claude should:

Never initiate git commits, pushes, pulls, or any write operations
Only use git for read-only informational purposes (status, diff, log, show)
Not proactively suggest git operations unless explicitly asked

Git write operations are blocked in .claude/settings.json to enforce this workflow.

Architecture Overview

Monorepo Structure (future plan)

root project: /coding-with-claude-application
packages (apps, microservices, utilities):
- cwc-types: shared TypeScript types to be used in all other packages
- cwc-utils: shared utilities for browser and Node.js (profanity checking, validation helpers, etc.)
- cwc-deployment: custom deployment CLI for SSH-based deployment to remote servers
- cwc-backend-utils: shared Node.js utilities that backend/api packages will consume
- cwc-website: public frontend end web application
- cwc-auth: authentication microservice, providing login, logout, signup, password reset, etc.
- cwc-api: the main data api used by cwc-website to read & write data, enforce auth, role-based access policies, and business rules/logic
- cwc-dashboard: an administrative web dashboard app for site owners to manage the app & data
- cwc-admin-api: the admin and data api used by the cwc-dashboard app
- cwc-database: database scripts to create tables, indexes, views, as well as insert configuration data
- cwc-schema: shared schema management library that may be used by frontend and backend packages
- cwc-sql: the only backend service that interacts directly with the database server, uses schema to dynamically generate sql statements
- cwc-e2e: a set of end-to-end tests

Tech Stack: to be determined as we build each package, update this documentation as we go.

Development Tooling & Infrastructure

Monorepo Management

pnpm v9.x + Turborepo v2.x

pnpm workspaces for package management and dependency resolution
- Configured in pnpm-workspace.yaml
- Packages located in packages/*
- Uses content-addressable storage for disk efficiency
- Strict dependency resolution prevents phantom dependencies
Turborepo for task orchestration and caching
- Configured in turbo.json
- Intelligent parallel execution based on dependency graph
- Local caching for faster rebuilds
- Pipeline tasks: build, dev, test, lint, typecheck

Node.js Version

Node.js 22 LTS (specified in .nvmrc)
Required for all development and production environments
Use nvm for version management

Code Quality Tools

TypeScript v5.4+

Configured in tsconfig.base.json
Strict mode enabled with enhanced type checking
JavaScript explicitly disallowed (allowJs: false)
Monorepo-optimized with composite projects
Individual packages extend base config

Module Resolution: bundler

Uses "moduleResolution": "bundler" in tsconfig.base.json
Uses "module": "ES2022" (required for bundler resolution)
Allows clean TypeScript imports without .js extensions
- ✅ Correct: import { Schema } from './types'
- ❌ Not needed: import { Schema } from './types.js'
Still produces correct ES module output in compiled JavaScript
Designed for TypeScript projects compiled by tsc or bundlers

Why bundler over NodeNext:

Better DX: No .js extensions in TypeScript source files
Modern standard: Industry standard for TypeScript libraries and monorepos
Same output: Still generates proper ES modules (.js files)
No trade-offs: Type safety and module compatibility maintained

ESLint v8.x with TypeScript

Configured in .eslintrc.json
Uses @typescript-eslint/strict ruleset
Enforces explicit function return types
Prohibits any type and non-null assertions
Strict boolean expressions required

Prettier v3.x

Configured in .prettierrc.json
Standards:
- Single quotes
- 2-space indentation
- 100 character line width
- Trailing commas (ES5)
- LF line endings

Root Scripts

Run from monorepo root using pnpm:

pnpm build - Build all packages (parallel, cached)
pnpm dev - Run all packages in dev mode
pnpm test - Run tests across all packages (parallel, cached)
pnpm lint - Lint all packages (parallel, cached)
pnpm typecheck - Type-check all packages (parallel, cached)
pnpm format - Format all files with Prettier
pnpm format:check - Check formatting without changes

Development Workflow

Before starting work:
- Ensure Node 22 is active: nvm use
- Install dependencies: pnpm install
During development:
- Run dev mode: pnpm dev (in specific package or root)
- Format code: pnpm format
Before committing:
- Type-check: pnpm typecheck
- Lint: pnpm lint
- Format check: pnpm format:check
- Run tests: pnpm test

Package Creation Conventions

When creating a new package in the monorepo:

Version Number: Always start new packages at version 1.0.0 (not 0.0.1)
- Example: "version": "1.0.0" in package.json
- This is a project preference for consistency
Package Structure:
- Follow existing package patterns (see cwc-types as reference)
- Include package.json, tsconfig.json extending base config
- Place source files in src/ directory
- Include appropriate build and typecheck scripts
Package Naming:
- Use cwc- prefix for all CWC packages
- Use kebab-case: cwc-types, cwc-backend-utils, etc.
Package Documentation:
- Create packages/{package-name}/CLAUDE.md for package-specific patterns and conventions
- Document architecture decisions, design patterns, and critical implementation details
- Keep package docs focused on information needed for AI-assisted coding

Key Architectural Decisions & Patterns

MariaDB Database

Strong Schema Enforcement
Transaction support
Efficient Joins
Data normalization
Sophisticated Querying and Analytics

Details: See packages/cwc-database/CLAUDE.md for complete database schema conventions.

TypeScript

Strict mode enabled (strict: true)
Shared types in cwc-types package; duplicating types in separate projects leads to inconsistencies, incompatibility, confusion, and extra work
Never use any - prefer unknown if type is truly unknown
Use string literal union types, not enums
Use type for entity definitions, not interface
Run typecheck before committing

Details: See packages/cwc-types/CLAUDE.md for complete TypeScript patterns and type generation.

Cloud-Agnostic Microservices

CWC uses a microservices architecture deployed as Docker containers potentially deployed across multiple datacenters.

Vendor lock-in is a real business risk. Cloud providers can change pricing, deny service access, or deprecate features at any time.
Cloud-agnostic microservices architecture allows switching hosting providers with minimal effort.
Preparation for Scale - can scale by adding infrastructure (more containers, load balancers) rather than rewriting code and specific services can be scaled based on actual load patterns

Environment Configuration

Each package will read configuration values from a .env file, provided at runtime, tailored to the runtime environment

Development Process

Tool, Framework, Version selection

mainstream, widely accepted, and thoroughly tested & proven tools only
the desire is to use the latest stable versions of the various tools

Adopt a "roll-your-own" mentality

we want to minimize the number of unnecessary dependencies to avoid headaches when upgrading our core tech stack
when it makes sense, we will build our own components and utilities rather than relying on a 3rd party package

packages/cwc-schema/CLAUDE.md

4 versions

Version 1

cwc-schema Package

Database schema definitions with validation rules for the CWC application. Provides a single source of truth for database structure, validation logic, and schema metadata.

Package Purpose

Define database table and view schemas programmatically
Provide runtime validation for entity data
Centralize column definitions and validation rules
Enable schema-driven tooling (future: SQL generation, admin interfaces)
Document database structure in TypeScript

Package Structure

cwc-schema/
├── src/
│   ├── types.ts                  - Core schema type definitions
│   ├── columnTypes.ts            - Reusable column definitions (36 types)
│   ├── validation/
│   │   ├── regexPatterns.ts     - Validation regex constants
│   │   └── validator.ts         - Runtime validation functions
│   ├── tables/                  - Table schema definitions (18 files)
│   │   ├── abuseReport.ts
│   │   ├── adminUser.ts
│   │   ├── ... (alphabetically ordered)
│   │   └── userJwt.ts
│   └── index.ts                 - Schema aggregator and exports
└── dist/                        - Compiled output

Architecture

Relationship to Other Packages

cwc-schema vs cwc-types:

cwc-schema: Validation rules, column metadata, schema structure (this package)
cwc-types: TypeScript entity types for compile-time safety (manually maintained)
Separation: Schema provides runtime validation; types provide compile-time safety
No codegen: Schema does NOT generate cwc-types (both maintained separately for now)
Future: May revisit to have schema generate types as single source of truth

Source of Truth:

Database: SQL scripts in cwc-database remain authoritative for database structure
Schema mirrors SQL: cwc-schema mirrors the SQL definitions for TypeScript/validation purposes
Manual sync: When SQL changes, update both cwc-schema AND cwc-types manually
Future: May transition to schema-first with SQL generation

Core Types

SchemaColumn: Defines a single database column with validation rules

type SchemaColumn = {
  type: 'string' | 'number' | 'boolean' | 'object';
  name: string;                    // Column name in database
  typename: string;                // Semantic category (uuid, email, pkid)
  required?: boolean;              // Whether column is required

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  values?: string[];               // Enum values

  // Number validation
  minValue?: number;
  maxValue?: number;

  // Foreign key metadata
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };
};

Schema: Defines a complete table or view schema

type Schema = {
  name: string;                    // Table/view name
  type: 'table' | 'view';
  version?: string;                // Schema version (e.g., '1.0.0')
  pkid: string | undefined;        // Primary key column name (undefined for views)
  columns: Record<string, SchemaColumn>;
};

Schema Definition Patterns

Reusable Column Types (Spread Syntax)

Pattern: Define base column types in columnTypes.ts, customize via spread syntax

// columnTypes.ts - Base definition
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
};

export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// tables/user.ts - Customized usage
userPkId: { ...pkid, name: 'userPkId' },
deviceId: { ...uuid, name: 'deviceId' },

Benefits:

DRY: Validation rules defined once, reused everywhere
Consistency: All UUIDs use same regex, all PKIDs have minValue: 0
Easy updates: Change validation in one place, applies everywhere
Type safety: TypeScript ensures column definitions are valid

Foreign Key Relationships

Pattern: Infer foreign keys from column names ending in PkId (except table's own PkId)

userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

projectPkId: {
  ...pkid,
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
},

Note: Foreign keys are metadata only; CWC database does NOT use DB-level FK constraints (see cwc-database/CLAUDE.md)

Enum-Like VARCHAR Fields

Pattern: Use values array to define allowed enum values

status: {
  type: 'string',
  typename: 'string',
  minLength: 4,
  maxLength: 25,
  values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
  name: 'status',
},

loginType: {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
},

Important: These values must match the potential-values comments in SQL and the union types in cwc-types

Required vs Optional Fields

Pattern: Mark fields as required: true only when they are NOT NULL in SQL AND cannot be null in business logic

// Required field (NOT NULL in SQL)
entityPkId: {
  ...pkid,
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
},

message: {
  ...mediumMessage,
  required: true,
},

// Optional field (NULL allowed in SQL)
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  // required omitted = optional
},

Note: Most standard columns (enabled, createdDate, modifiedDate) are optional in schema even though they're always populated, because SQL allows NULL

Adding New Tables

Steps to add a new table schema:

Add SQL first: Update packages/cwc-database/schema-definition/create-tables.sql
Create schema file: packages/cwc-schema/src/tables/{tableName}.ts
Define schema: Follow existing patterns, use spread syntax for common columns
Add to index: Import and add to schemas.tables object in src/index.ts (alphabetically!)
Add entity type: Create corresponding type in packages/cwc-types/src/entityTypes.ts
Verify alphabetical order: Run validateAlphabeticalOrder() in tests

Template:

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate } from '../columnTypes';

export const {tableName}Schema: Schema = {
  name: '{tableName}',
  type: 'table',
  version: '1.0.0',
  pkid: '{tableName}PkId',
  columns: {
    {tableName}PkId: { ...pkid, name: '{tableName}PkId' },
    enabled,
    createdDate,
    modifiedDate,
    // ... custom columns
  },
};

Adding New Column Types

When to create a new reusable column type:

Column appears in 3+ tables with identical validation rules
Column has complex validation (regex, specific min/max values)
Column represents a semantic type (email, phone, UUID)

Steps:

Add to src/columnTypes.ts
Export the constant
Use via spread syntax in table schemas

Example:

// columnTypes.ts
export const phoneNumber: SchemaColumn = {
  type: 'string',
  minLength: 10,
  maxLength: 15,
  regex: PHONE_REGEX,
  name: 'phoneNumber',
  typename: 'phoneNumber',
};

// tables/user.ts
phone: { ...phoneNumber, name: 'phone' },

Runtime Validation

Usage:

import { validateEntity, validateColumn, getSchema } from 'cwc-schema';

// Validate a single column
const result = validateColumn('test@example.com', emailColumn);
if (!result.valid) {
  console.error(result.errors);
}

// Validate entire entity
const userSchema = getSchema('user');
const validationResult = validateEntity(userData, userSchema);
if (!validationResult.valid) {
  console.error(validationResult.errors);
}

// Validate partial entity (for updates)
const updateResult = validatePartialEntity({ email: 'new@example.com' }, userSchema);

Validation Functions:

validateColumn(value, column, fieldName?) - Validate single field
validateEntity(data, schema) - Validate complete entity (all required fields)
validatePartialEntity(data, schema) - Validate partial entity (ignores required constraint)

Validation Errors:

type ValidationError = {
  field: string;      // Column name
  message: string;    // Human-readable error
  value?: unknown;    // The invalid value
};

Schema Aggregation

Access schemas:

import { schemas, getSchema, getAllSchemas } from 'cwc-schema';

// Get specific schema by name
const userSchema = getSchema('user');

// Get all schemas as array
const allSchemas = getAllSchemas();

// Access organized by type
const projectSchema = schemas.tables.project;

Helper functions:

getSchema(name: string): Schema | undefined - Find schema by name
getAllSchemas(): Schema[] - Get all schemas (tables + views)
validateAlphabeticalOrder(): void - Throws if schemas not alphabetically ordered

Alphabetical Ordering Requirement

Critical: All table schemas MUST be alphabetically ordered in src/index.ts

Enforcement:

Call validateAlphabeticalOrder() in tests
Throws error with expected vs actual order if violated

Rationale:

Prevents merge conflicts
Makes finding schemas easier
Ensures consistency across the codebase

Column Type Semantic Categories (typename)

Common typenames:

pkid - Primary key or foreign key integer
uuid - UUID v4 identifier (36 chars)
email - Email address
username - Username field
password - Password hash
deviceId - Device UUID
foreignKey - Foreign key reference
boolean - Boolean/TINYINT field
createdDate, modifiedDate, loginDate - Timestamp fields
string - Generic string field
text - Long text field (TEXT type)

Purpose:

Groups similar columns across tables
Enables generic tooling (e.g., admin UI knows how to render 'email' fields)
Self-documenting schema

Regex Patterns

Defined in src/validation/regexPatterns.ts:

EMAIL_REGEX - Email address validation
UUID_REGEX - UUID v4 format
USERNAME_REGEX - Alphanumeric + underscores, 4-100 chars
CONFIRMATION_CODE_REGEX - 6-character codes
PROJECT_ID_REGEX - URL-friendly project identifiers
FILENAME_REGEX - Valid filenames

Usage:

import { EMAIL_REGEX } from 'cwc-schema';

const emailColumn: SchemaColumn = {
  type: 'string',
  regex: EMAIL_REGEX,
  // ...
};

Future Enhancements

Potential future features (not implemented yet):

SQL Generation: Generate CREATE TABLE statements from schema
Type Generation: Generate cwc-types from schema (single source of truth)
Migration Diffing: Compare schema versions to generate migration SQL
Schema Validation: Validate schema matches actual database structure
Admin UI Generation: Auto-generate CRUD interfaces from schema
API Documentation: Generate API docs from schema metadata

Related Packages

Consumed By:

Backend microservices (cwc-api, cwc-sql, cwc-auth) for runtime validation
Future admin tools and generic CRUD interfaces

Depends On:

None (zero runtime dependencies by design)

Related:

cwc-database: SQL scripts are source of truth; schema mirrors them
cwc-types: Provides compile-time types; schema provides runtime validation

Version 2

cwc-schema Package

Database schema definitions with validation rules for the CWC application. Provides a single source of truth for database structure, validation logic, and schema metadata.

Package Purpose

Define database table and view schemas programmatically
Provide runtime validation for entity data
Centralize column definitions and validation rules
Enable schema-driven tooling (future: SQL generation, admin interfaces)
Document database structure in TypeScript

Package Structure

cwc-schema/
├── src/
│   ├── types.ts                  - Core schema type definitions
│   ├── columnTypes.ts            - Reusable column definitions (36 types)
│   ├── validation/
│   │   ├── regexPatterns.ts     - Validation regex constants
│   │   ├── validator.ts         - Runtime validation functions
│   │   └── zodValidators.ts     - Example Zod validators for complex cases
│   ├── tables/                  - Table schema definitions (18 files)
│   │   ├── abuseReport.ts
│   │   ├── adminUser.ts
│   │   ├── ... (alphabetically ordered)
│   │   └── userJwt.ts
│   └── index.ts                 - Schema aggregator and exports
└── dist/                        - Compiled output

Architecture

Relationship to Other Packages

cwc-schema vs cwc-types:

cwc-schema: Validation rules, column metadata, schema structure (this package)
cwc-types: TypeScript entity types for compile-time safety (manually maintained)
Separation: Schema provides runtime validation; types provide compile-time safety
No codegen: Schema does NOT generate cwc-types (both maintained separately for now)
Future: May revisit to have schema generate types as single source of truth

Source of Truth:

Database: SQL scripts in cwc-database remain authoritative for database structure
Schema mirrors SQL: cwc-schema mirrors the SQL definitions for TypeScript/validation purposes
Manual sync: When SQL changes, update both cwc-schema AND cwc-types manually
Future: May transition to schema-first with SQL generation

Core Types

SchemaColumn: Defines a single database column with validation rules

type SchemaColumn = {
  type: 'string' | 'number' | 'boolean' | 'object';
  name: string;                    // Column name in database
  typename: string;                // Semantic category (uuid, email, pkid)
  required?: boolean;              // Whether column is required

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  values?: string[];               // Enum values

  // Number validation
  minValue?: number;
  maxValue?: number;

  // Foreign key metadata
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };

  // Hybrid validation (optional Zod)
  zodValidator?: z.ZodType<unknown>;  // When present, Zod validation is used
};

Schema: Defines a complete table or view schema

type Schema = {
  name: string;                    // Table/view name
  type: 'table' | 'view';
  version?: string;                // Schema version (e.g., '1.0.0')
  pkid: string | undefined;        // Primary key column name (undefined for views)
  columns: Record<string, SchemaColumn>;
};

Schema Definition Patterns

Reusable Column Types (Spread Syntax)

Pattern: Define base column types in columnTypes.ts, customize via spread syntax

// columnTypes.ts - Base definition
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
};

export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// tables/user.ts - Customized usage
userPkId: { ...pkid, name: 'userPkId' },
deviceId: { ...uuid, name: 'deviceId' },

Benefits:

DRY: Validation rules defined once, reused everywhere
Consistency: All UUIDs use same regex, all PKIDs have minValue: 0
Easy updates: Change validation in one place, applies everywhere
Type safety: TypeScript ensures column definitions are valid

Foreign Key Relationships

Pattern: Infer foreign keys from column names ending in PkId (except table's own PkId)

userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

projectPkId: {
  ...pkid,
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
},

Note: Foreign keys are metadata only; CWC database does NOT use DB-level FK constraints (see cwc-database/CLAUDE.md)

Enum-Like VARCHAR Fields

Pattern: Use values array to define allowed enum values

status: {
  type: 'string',
  typename: 'string',
  minLength: 4,
  maxLength: 25,
  values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
  name: 'status',
},

loginType: {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
},

Important: These values must match the potential-values comments in SQL and the union types in cwc-types

Required vs Optional Fields

Pattern: Mark fields as required: true only when they are NOT NULL in SQL AND cannot be null in business logic

// Required field (NOT NULL in SQL)
entityPkId: {
  ...pkid,
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
},

message: {
  ...mediumMessage,
  required: true,
},

// Optional field (NULL allowed in SQL)
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  // required omitted = optional
},

Note: Most standard columns (enabled, createdDate, modifiedDate) are optional in schema even though they're always populated, because SQL allows NULL

Adding New Tables

Steps to add a new table schema:

Add SQL first: Update packages/cwc-database/schema-definition/create-tables.sql
Create schema file: packages/cwc-schema/src/tables/{tableName}.ts
Define schema: Follow existing patterns, use spread syntax for common columns
Add to index: Import and add to schemas.tables object in src/index.ts (alphabetically!)
Add entity type: Create corresponding type in packages/cwc-types/src/entityTypes.ts
Verify alphabetical order: Run validateAlphabeticalOrder() in tests

Template:

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate } from '../columnTypes';

export const {tableName}Schema: Schema = {
  name: '{tableName}',
  type: 'table',
  version: '1.0.0',
  pkid: '{tableName}PkId',
  columns: {
    {tableName}PkId: { ...pkid, name: '{tableName}PkId' },
    enabled,
    createdDate,
    modifiedDate,
    // ... custom columns
  },
};

Adding New Column Types

When to create a new reusable column type:

Column appears in 3+ tables with identical validation rules
Column has complex validation (regex, specific min/max values)
Column represents a semantic type (email, phone, UUID)

Steps:

Add to src/columnTypes.ts
Export the constant
Use via spread syntax in table schemas

Example:

// columnTypes.ts
export const phoneNumber: SchemaColumn = {
  type: 'string',
  minLength: 10,
  maxLength: 15,
  regex: PHONE_REGEX,
  name: 'phoneNumber',
  typename: 'phoneNumber',
};

// tables/user.ts
phone: { ...phoneNumber, name: 'phone' },

Runtime Validation

Usage:

import { validateEntity, validateColumn, getSchema } from 'cwc-schema';

// Validate a single column
const result = validateColumn('test@example.com', emailColumn);
if (!result.valid) {
  console.error(result.errors);
}

// Validate entire entity
const userSchema = getSchema('user');
const validationResult = validateEntity(userData, userSchema);
if (!validationResult.valid) {
  console.error(validationResult.errors);
}

// Validate partial entity (for updates)
const updateResult = validatePartialEntity({ email: 'new@example.com' }, userSchema);

Validation Functions:

validateColumn(value, column, fieldName?) - Validate single field
validateEntity(data, schema) - Validate complete entity (all required fields)
validatePartialEntity(data, schema) - Validate partial entity (ignores required constraint)

Validation Errors:

type ValidationError = {
  field: string;      // Column name
  message: string;    // Human-readable error
  value?: unknown;    // The invalid value
};

Hybrid Validation with Zod

Architecture: cwc-schema uses a hybrid validation approach that combines custom validation (default) with optional Zod validators (opt-in).

When to Use Zod vs Custom Validation

Use Zod validators for:

Password strength requirements (uppercase, lowercase, numbers, special chars)
Conditional validation (different rules based on context)
Cross-field validation (one field depends on another)
Complex business logic requiring custom refinements
Advanced string parsing (dates, URLs, transformations)
Nested object/array validation
Profanity filters, blacklists, or complex content rules

Use custom validation for:

Simple min/max length checks
Simple regex patterns (email, UUID, username)
Basic enum values (status, type fields)
Basic type checking (string, number, boolean)
Foreign key references
Most standard columns (enabled, createdDate, etc.)

How Hybrid Validation Works

Custom validation is default: All existing schemas use custom validation
Zod is opt-in: Add zodValidator field to any column to use Zod
No breaking changes: Existing code continues to work unchanged
Validation precedence: When zodValidator is present, Zod is used; otherwise custom validation runs

Adding Zod Validators to Columns

Step 1: Import or create a Zod validator

import { passwordStrengthValidator } from '../validation/zodValidators';

Step 2: Add zodValidator field to column definition

// Before (custom validation)
password: {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
},

// After (Zod validation)
password: {
  type: 'string',
  minLength: 8,  // Still useful for documentation
  maxLength: 100,
  name: 'password',
  typename: 'password',
  zodValidator: passwordStrengthValidator,  // Zod takes precedence
},

Important: Keep type, minLength, maxLength etc. even when using Zod - they serve as documentation and fallback.

Creating Custom Zod Validators

Example validators are in src/validation/zodValidators.ts:

// Simple password strength validator
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

// Reusable validator factory
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        try {
          const url = new URL(val);
          return allowedDomains.some((domain) =>
            url.hostname === domain || url.hostname.endsWith(`.${domain}`)
          );
        } catch {
          return false;
        }
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

Best Practices

1. Start simple, adopt gradually:

Don't migrate everything to Zod at once
Use Zod only where complexity justifies it
Keep custom validation for simple cases

2. Reuse validators:

Create validator library in zodValidators.ts
Export reusable validators for common patterns
Use factory functions for configurable validators

3. Maintain documentation fields:

Keep minLength, maxLength, values etc. for documentation
These fields help developers understand constraints without reading Zod code
Serves as fallback if Zod validator is removed

4. Error messages:

Provide clear, user-friendly error messages in Zod refinements
Zod errors are automatically converted to ValidationError format
Users see the same error structure regardless of validation method

5. Type safety:

Use z.ZodType<unknown> for the zodValidator field type
TypeScript ensures Zod validators are properly typed
Validation happens at runtime, types are enforced at compile time

Migration Path

Gradual adoption recommended:

Phase 1: Use custom validation for all schemas (current state for most schemas)
Phase 2: Add Zod validators to complex cases (passwords, emails with strict rules)
Phase 3: Evaluate if simple cases benefit from Zod (probably not)
Phase 4: Consider full Zod migration only if benefits are clear

No forced migration: Custom validation remains fully supported and is appropriate for most use cases.

Schema Column Type Definition

type SchemaColumn = {
  // ... existing fields ...

  /**
   * Optional Zod validator for complex validation logic.
   * When present, Zod validation is used instead of custom validation.
   * Allows opt-in to Zod for complex cases while maintaining custom validation as default.
   */
  zodValidator?: z.ZodType<unknown>;
};

Schema Aggregation

Access schemas:

import { schemas, getSchema, getAllSchemas } from 'cwc-schema';

// Get specific schema by name
const userSchema = getSchema('user');

// Get all schemas as array
const allSchemas = getAllSchemas();

// Access organized by type
const projectSchema = schemas.tables.project;

Helper functions:

getSchema(name: string): Schema | undefined - Find schema by name
getAllSchemas(): Schema[] - Get all schemas (tables + views)
validateAlphabeticalOrder(): void - Throws if schemas not alphabetically ordered

Alphabetical Ordering Requirement

Critical: All table schemas MUST be alphabetically ordered in src/index.ts

Enforcement:

Call validateAlphabeticalOrder() in tests
Throws error with expected vs actual order if violated

Rationale:

Prevents merge conflicts
Makes finding schemas easier
Ensures consistency across the codebase

Column Type Semantic Categories (typename)

Common typenames:

pkid - Primary key or foreign key integer
uuid - UUID v4 identifier (36 chars)
email - Email address
username - Username field
password - Password hash
deviceId - Device UUID
foreignKey - Foreign key reference
boolean - Boolean/TINYINT field
createdDate, modifiedDate, loginDate - Timestamp fields
string - Generic string field
text - Long text field (TEXT type)

Purpose:

Groups similar columns across tables
Enables generic tooling (e.g., admin UI knows how to render 'email' fields)
Self-documenting schema

Regex Patterns

Defined in src/validation/regexPatterns.ts:

EMAIL_REGEX - Email address validation
UUID_REGEX - UUID v4 format
USERNAME_REGEX - Alphanumeric + underscores, 4-100 chars
CONFIRMATION_CODE_REGEX - 6-character codes
PROJECT_ID_REGEX - URL-friendly project identifiers
FILENAME_REGEX - Valid filenames

Usage:

import { EMAIL_REGEX } from 'cwc-schema';

const emailColumn: SchemaColumn = {
  type: 'string',
  regex: EMAIL_REGEX,
  // ...
};

Future Enhancements

Potential future features (not implemented yet):

SQL Generation: Generate CREATE TABLE statements from schema
Type Generation: Generate cwc-types from schema (single source of truth)
Migration Diffing: Compare schema versions to generate migration SQL
Schema Validation: Validate schema matches actual database structure
Admin UI Generation: Auto-generate CRUD interfaces from schema
API Documentation: Generate API docs from schema metadata

Related Packages

Consumed By:

Backend microservices (cwc-api, cwc-sql, cwc-auth) for runtime validation
Future admin tools and generic CRUD interfaces

Depends On:

None (zero runtime dependencies by design)

Related:

cwc-database: SQL scripts are source of truth; schema mirrors them
cwc-types: Provides compile-time types; schema provides runtime validation

Version 3

cwc-schema Package

Database schema definitions with validation rules for the CWC application. Provides a single source of truth for database structure, validation logic, and schema metadata.

Package Purpose

Define database table and view schemas programmatically
Provide runtime validation for entity data
Centralize column definitions and validation rules
Enable schema-driven tooling (future: SQL generation, admin interfaces)
Document database structure in TypeScript

Package Structure

cwc-schema/
├── src/
│   ├── types.ts                  - Core schema type definitions
│   ├── columnTypes.ts            - Reusable column definitions (36 types)
│   ├── validation/
│   │   ├── regexPatterns.ts     - Validation regex constants
│   │   ├── validator.ts         - Runtime validation functions
│   │   └── zodValidators.ts     - Example Zod validators for complex cases
│   ├── tables/                  - Table schema definitions (18 files)
│   │   ├── abuseReport.ts
│   │   ├── adminUser.ts
│   │   ├── ... (alphabetically ordered)
│   │   └── userJwt.ts
│   └── index.ts                 - Schema aggregator and exports
└── dist/                        - Compiled output

Architecture

Relationship to Other Packages

cwc-schema vs cwc-types:

cwc-schema: Validation rules, column metadata, schema structure (this package)
cwc-types: TypeScript entity types for compile-time safety (manually maintained)
Separation: Schema provides runtime validation; types provide compile-time safety
No codegen: Schema does NOT generate cwc-types (both maintained separately for now)
Future: May revisit to have schema generate types as single source of truth

Source of Truth:

Database: SQL scripts in cwc-database remain authoritative for database structure
Schema mirrors SQL: cwc-schema mirrors the SQL definitions for TypeScript/validation purposes
Manual sync: When SQL changes, update both cwc-schema AND cwc-types manually
Future: May transition to schema-first with SQL generation

Core Types

SchemaColumn: Defines a single database column with validation rules

type SchemaColumn = {
  type: 'string' | 'number' | 'boolean' | 'object';
  name: string;                    // Column name in database
  typename: string;                // Semantic category (uuid, email, pkid)
  required?: boolean;              // Whether column is required

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  values?: string[];               // Enum values

  // Number validation
  minValue?: number;
  maxValue?: number;

  // Foreign key metadata
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };

  // Hybrid validation (optional Zod)
  zodValidator?: z.ZodType<unknown>;  // When present, Zod validation is used
};

Schema: Defines a complete table or view schema

type Schema = {
  name: string;                    // Table/view name
  type: 'table' | 'view';
  version?: string;                // Schema version (e.g., '1.0.0')
  pkid: string | undefined;        // Primary key column name (undefined for views)
  columns: Record<string, SchemaColumn>;
};

Schema Definition Patterns

Reusable Column Types (Spread Syntax)

Pattern: Define base column types in columnTypes.ts, customize via spread syntax

// columnTypes.ts - Base definition
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
};

export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// tables/user.ts - Customized usage
userPkId: { ...pkid, name: 'userPkId' },
deviceId: { ...uuid, name: 'deviceId' },

Benefits:

DRY: Validation rules defined once, reused everywhere
Consistency: All UUIDs use same regex, all PKIDs have minValue: 0
Easy updates: Change validation in one place, applies everywhere
Type safety: TypeScript ensures column definitions are valid

Foreign Key Relationships

Pattern: Infer foreign keys from column names ending in PkId (except table's own PkId)

userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

projectPkId: {
  ...pkid,
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
},

Note: Foreign keys are metadata only; CWC database does NOT use DB-level FK constraints (see cwc-database/CLAUDE.md)

Enum-Like VARCHAR Fields

Pattern: Use values array to define allowed enum values

status: {
  type: 'string',
  typename: 'string',
  minLength: 4,
  maxLength: 25,
  values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
  name: 'status',
},

loginType: {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
},

Important: These values must match the potential-values comments in SQL and the union types in cwc-types

Required vs Optional Fields

Pattern: Mark fields as required: true only when they are NOT NULL in SQL AND cannot be null in business logic

// Required field (NOT NULL in SQL)
entityPkId: {
  ...pkid,
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
},

message: {
  ...mediumMessage,
  required: true,
},

// Optional field (NULL allowed in SQL)
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  // required omitted = optional
},

Note: Most standard columns (enabled, createdDate, modifiedDate) are optional in schema even though they're always populated, because SQL allows NULL

Adding New Tables

Steps to add a new table schema:

Add SQL first: Update packages/cwc-database/schema-definition/create-tables.sql
Create schema file: packages/cwc-schema/src/tables/{tableName}.ts
Define schema: Follow existing patterns, use spread syntax for common columns
Add to index: Import and add to schemas.tables object in src/index.ts (alphabetically!)
Add entity type: Create corresponding type in packages/cwc-types/src/entityTypes.ts
Verify alphabetical order: Run validateAlphabeticalOrder() in tests

Template:

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate } from '../columnTypes';

export const {tableName}Schema: Schema = {
  name: '{tableName}',
  type: 'table',
  version: '1.0.0',
  pkid: '{tableName}PkId',
  columns: {
    {tableName}PkId: { ...pkid, name: '{tableName}PkId' },
    enabled,
    createdDate,
    modifiedDate,
    // ... custom columns
  },
};

Adding New Column Types

When to create a new reusable column type:

Column appears in 3+ tables with identical validation rules
Column has complex validation (regex, specific min/max values)
Column represents a semantic type (email, phone, UUID)

Steps:

Add to src/columnTypes.ts
Export the constant
Use via spread syntax in table schemas

Example:

// columnTypes.ts
export const phoneNumber: SchemaColumn = {
  type: 'string',
  minLength: 10,
  maxLength: 15,
  regex: PHONE_REGEX,
  name: 'phoneNumber',
  typename: 'phoneNumber',
};

// tables/user.ts
phone: { ...phoneNumber, name: 'phone' },

Runtime Validation

Usage:

import { validateEntity, validateColumn, getSchema } from 'cwc-schema';

// Validate a single column
const result = validateColumn('test@example.com', emailColumn);
if (!result.valid) {
  console.error(result.errors);
}

// Validate entire entity
const userSchema = getSchema('user');
const validationResult = validateEntity(userData, userSchema);
if (!validationResult.valid) {
  console.error(validationResult.errors);
}

// Validate partial entity (for updates)
const updateResult = validatePartialEntity({ email: 'new@example.com' }, userSchema);

Validation Functions:

validateColumn(value, column, fieldName?) - Validate single field
validateEntity(data, schema) - Validate complete entity (all required fields)
validatePartialEntity(data, schema) - Validate partial entity (ignores required constraint)

Validation Errors:

type ValidationError = {
  field: string;      // Column name
  message: string;    // Human-readable error
  value?: unknown;    // The invalid value
};

Hybrid Validation with Zod

Architecture: cwc-schema uses a hybrid validation approach that combines custom validation (default) with optional Zod validators (opt-in).

When to Use Zod vs Custom Validation

Use Zod validators for:

Password strength requirements (uppercase, lowercase, numbers, special chars)
Conditional validation (different rules based on context)
Cross-field validation (one field depends on another)
Complex business logic requiring custom refinements
Advanced string parsing (dates, URLs, transformations)
Nested object/array validation
Profanity filters, blacklists, or complex content rules

Use custom validation for:

Simple min/max length checks
Simple regex patterns (email, UUID, username)
Basic enum values (status, type fields)
Basic type checking (string, number, boolean)
Foreign key references
Most standard columns (enabled, createdDate, etc.)

How Hybrid Validation Works

Custom validation is default: All existing schemas use custom validation
Zod is opt-in: Add zodValidator field to any column to use Zod
No breaking changes: Existing code continues to work unchanged
Validation precedence: When zodValidator is present, Zod is used; otherwise custom validation runs

Adding Zod Validators to Columns

Step 1: Import or create a Zod validator

import { passwordStrengthValidator } from '../validation/zodValidators';

Step 2: Add zodValidator field to column definition

// Before (custom validation)
password: {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
},

// After (Zod validation)
password: {
  type: 'string',
  minLength: 8,  // Still useful for documentation
  maxLength: 100,
  name: 'password',
  typename: 'password',
  zodValidator: passwordStrengthValidator,  // Zod takes precedence
},

Important: Keep type, minLength, maxLength etc. even when using Zod - they serve as documentation and fallback.

Creating Custom Zod Validators

Example validators are in src/validation/zodValidators.ts:

// Simple password strength validator
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

// Reusable validator factory
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        try {
          const url = new URL(val);
          return allowedDomains.some((domain) =>
            url.hostname === domain || url.hostname.endsWith(`.${domain}`)
          );
        } catch {
          return false;
        }
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

Best Practices

1. Start simple, adopt gradually:

Don't migrate everything to Zod at once
Use Zod only where complexity justifies it
Keep custom validation for simple cases

2. Reuse validators:

Create validator library in zodValidators.ts
Export reusable validators for common patterns
Use factory functions for configurable validators

3. Maintain documentation fields:

Keep minLength, maxLength, values etc. for documentation
These fields help developers understand constraints without reading Zod code
Serves as fallback if Zod validator is removed

4. Error messages:

Provide clear, user-friendly error messages in Zod refinements
Zod errors are automatically converted to ValidationError format
Users see the same error structure regardless of validation method

5. Type safety:

Use z.ZodType<unknown> for the zodValidator field type
TypeScript ensures Zod validators are properly typed
Validation happens at runtime, types are enforced at compile time

Migration Path

Gradual adoption recommended:

Phase 1: Use custom validation for all schemas (current state for most schemas)
Phase 2: Add Zod validators to complex cases (passwords, emails with strict rules)
Phase 3: Evaluate if simple cases benefit from Zod (probably not)
Phase 4: Consider full Zod migration only if benefits are clear

No forced migration: Custom validation remains fully supported and is appropriate for most use cases.

Schema Column Type Definition

type SchemaColumn = {
  // ... existing fields ...

  /**
   * Optional Zod validator for complex validation logic.
   * When present, Zod validation is used instead of custom validation.
   * Allows opt-in to Zod for complex cases while maintaining custom validation as default.
   */
  zodValidator?: z.ZodType<unknown>;
};

Schema Aggregation

Access schemas:

import { schemas, getSchema, getAllSchemas } from 'cwc-schema';

// Get specific schema by name
const userSchema = getSchema('user');

// Get all schemas as array
const allSchemas = getAllSchemas();

// Access organized by type
const projectSchema = schemas.tables.project;

Helper functions:

getSchema(name: string): Schema | undefined - Find schema by name
getAllSchemas(): Schema[] - Get all schemas (tables + views)
validateAlphabeticalOrder(): void - Throws if schemas not alphabetically ordered

Alphabetical Ordering Requirement

Critical: All table schemas MUST be alphabetically ordered in src/index.ts

Enforcement:

Call validateAlphabeticalOrder() in tests
Throws error with expected vs actual order if violated

Rationale:

Prevents merge conflicts
Makes finding schemas easier
Ensures consistency across the codebase

Column Type Semantic Categories (typename)

Common typenames:

pkid - Primary key or foreign key integer
uuid - UUID v4 identifier (36 chars)
email - Email address
username - Username field
password - Password hash
deviceId - Device UUID
foreignKey - Foreign key reference
boolean - Boolean/TINYINT field
createdDate, modifiedDate, loginDate - Timestamp fields
string - Generic string field
text - Long text field (TEXT type)

Purpose:

Groups similar columns across tables
Enables generic tooling (e.g., admin UI knows how to render 'email' fields)
Self-documenting schema

Regex Patterns

Defined in src/validation/regexPatterns.ts:

EMAIL_REGEX - Email address validation
UUID_REGEX - UUID v4 format
USERNAME_REGEX - Alphanumeric + underscores, 4-100 chars
CONFIRMATION_CODE_REGEX - 6-character codes
PROJECT_ID_REGEX - URL-friendly project identifiers
FILENAME_REGEX - Valid filenames

Usage:

import { EMAIL_REGEX } from 'cwc-schema';

const emailColumn: SchemaColumn = {
  type: 'string',
  regex: EMAIL_REGEX,
  // ...
};

Future Enhancements

Potential future features (not implemented yet):

SQL Generation: Generate CREATE TABLE statements from schema
Type Generation: Generate cwc-types from schema (single source of truth)
Migration Diffing: Compare schema versions to generate migration SQL
Schema Validation: Validate schema matches actual database structure
Admin UI Generation: Auto-generate CRUD interfaces from schema
API Documentation: Generate API docs from schema metadata

Related Packages

Consumed By:

Backend microservices (cwc-api, cwc-sql, cwc-auth) for runtime validation
Future admin tools and generic CRUD interfaces

Depends On:

None (zero runtime dependencies by design)

Related:

cwc-database: SQL scripts are source of truth; schema mirrors them
cwc-types: Provides compile-time types; schema provides runtime validation

Version 4 (latest)

cwc-schema Package

Database schema definitions with validation rules for the CWC application. Provides a single source of truth for database structure, validation logic, and schema metadata.

Package Purpose

Define database table and view schemas programmatically
Provide runtime validation for entity data
Centralize column definitions and validation rules
Enable schema-driven tooling (future: SQL generation, admin interfaces)
Document database structure in TypeScript

Package Structure

cwc-schema/
├── src/
│   ├── types.ts                  - Core schema type definitions
│   ├── columnTypes.ts            - Reusable column definitions (36 types)
│   ├── validation/
│   │   ├── regexPatterns.ts     - Validation regex constants
│   │   ├── validator.ts         - Runtime validation functions
│   │   └── zodValidators.ts     - Example Zod validators for complex cases
│   ├── tables/                  - Table schema definitions (18 files)
│   │   ├── abuseReport.ts
│   │   ├── adminUser.ts
│   │   ├── ... (alphabetically ordered)
│   │   └── userJwt.ts
│   └── index.ts                 - Schema aggregator and exports
└── dist/                        - Compiled output

Architecture

Relationship to Other Packages

cwc-schema vs cwc-types:

cwc-schema: Validation rules, column metadata, schema structure (this package)
cwc-types: TypeScript entity types for compile-time safety (manually maintained)
Separation: Schema provides runtime validation; types provide compile-time safety
No codegen: Schema does NOT generate cwc-types (both maintained separately for now)
Future: May revisit to have schema generate types as single source of truth

Source of Truth:

Database: SQL scripts in cwc-database remain authoritative for database structure
Schema mirrors SQL: cwc-schema mirrors the SQL definitions for TypeScript/validation purposes
Manual sync: When SQL changes, update both cwc-schema AND cwc-types manually
Future: May transition to schema-first with SQL generation

Core Types

SchemaColumn: Defines a single database column with validation rules

type SchemaColumn = {
  type: 'string' | 'number' | 'boolean' | 'object';
  name: string;                    // Column name in database
  typename: string;                // Semantic category (uuid, email, pkid)
  required?: boolean;              // Whether column is required

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  values?: string[];               // Enum values

  // Number validation
  minValue?: number;
  maxValue?: number;

  // Foreign key metadata
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };

  // Hybrid validation (optional Zod)
  zodValidator?: z.ZodType<unknown>;  // When present, Zod validation is used
};

Schema: Defines a complete table or view schema

type Schema = {
  name: string;                    // Table/view name
  type: 'table' | 'view';
  version?: string;                // Schema version (e.g., '1.0.0')
  pkid: string | undefined;        // Primary key column name (undefined for views)
  columns: Record<string, SchemaColumn>;
};

Schema Definition Patterns

Reusable Column Types (Spread Syntax)

Pattern: Define base column types in columnTypes.ts, customize via spread syntax

// columnTypes.ts - Base definition
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
};

export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// tables/user.ts - Customized usage
userPkId: { ...pkid, name: 'userPkId' },
deviceId: { ...uuid, name: 'deviceId' },

Benefits:

DRY: Validation rules defined once, reused everywhere
Consistency: All UUIDs use same regex, all PKIDs have minValue: 0
Easy updates: Change validation in one place, applies everywhere
Type safety: TypeScript ensures column definitions are valid

Foreign Key Relationships

Pattern: Infer foreign keys from column names ending in PkId (except table's own PkId)

userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
},

projectPkId: {
  ...pkid,
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
},

Note: Foreign keys are metadata only; CWC database does NOT use DB-level FK constraints (see cwc-database/CLAUDE.md)

Enum-Like VARCHAR Fields

Pattern: Use values array to define allowed enum values

status: {
  type: 'string',
  typename: 'string',
  minLength: 4,
  maxLength: 25,
  values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
  name: 'status',
},

loginType: {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
},

Important: These values must match the potential-values comments in SQL and the union types in cwc-types

Required vs Optional Fields

Pattern: Mark fields as required: true only when they are NOT NULL in SQL AND cannot be null in business logic

// Required field (NOT NULL in SQL)
entityPkId: {
  ...pkid,
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
},

message: {
  ...mediumMessage,
  required: true,
},

// Optional field (NULL allowed in SQL)
userPkId: {
  ...pkid,
  name: 'userPkId',
  typename: 'foreignKey',
  // required omitted = optional
},

Note: Most standard columns (enabled, createdDate, modifiedDate) are optional in schema even though they're always populated, because SQL allows NULL

Adding New Tables

Steps to add a new table schema:

Add SQL first: Update packages/cwc-database/schema-definition/create-tables.sql
Create schema file: packages/cwc-schema/src/tables/{tableName}.ts
Define schema: Follow existing patterns, use spread syntax for common columns
Add to index: Import and add to schemas.tables object in src/index.ts (alphabetically!)
Add entity type: Create corresponding type in packages/cwc-types/src/entityTypes.ts
Verify alphabetical order: Run validateAlphabeticalOrder() in tests

Template:

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate } from '../columnTypes';

export const {tableName}Schema: Schema = {
  name: '{tableName}',
  type: 'table',
  version: '1.0.0',
  pkid: '{tableName}PkId',
  columns: {
    {tableName}PkId: { ...pkid, name: '{tableName}PkId' },
    enabled,
    createdDate,
    modifiedDate,
    // ... custom columns
  },
};

Adding New Column Types

When to create a new reusable column type:

Column appears in 3+ tables with identical validation rules
Column has complex validation (regex, specific min/max values)
Column represents a semantic type (email, phone, UUID)

Steps:

Add to src/columnTypes.ts
Export the constant
Use via spread syntax in table schemas

Example:

// columnTypes.ts
export const phoneNumber: SchemaColumn = {
  type: 'string',
  minLength: 10,
  maxLength: 15,
  regex: PHONE_REGEX,
  name: 'phoneNumber',
  typename: 'phoneNumber',
};

// tables/user.ts
phone: { ...phoneNumber, name: 'phone' },

Runtime Validation

Usage:

import { validateEntity, validateColumn, getSchema } from 'cwc-schema';

// Validate a single column
const result = validateColumn('test@example.com', emailColumn);
if (!result.valid) {
  console.error(result.errors);
}

// Validate entire entity
const userSchema = getSchema('user');
const validationResult = validateEntity(userData, userSchema);
if (!validationResult.valid) {
  console.error(validationResult.errors);
}

// Validate partial entity (for updates)
const updateResult = validatePartialEntity({ email: 'new@example.com' }, userSchema);

Validation Functions:

validateColumn(value, column, fieldName?) - Validate single field
validateEntity(data, schema) - Validate complete entity (all required fields)
validatePartialEntity(data, schema) - Validate partial entity (ignores required constraint)

Validation Errors:

type ValidationError = {
  field: string;      // Column name
  message: string;    // Human-readable error
  value?: unknown;    // The invalid value
};

Hybrid Validation with Zod

Architecture: cwc-schema uses a hybrid validation approach that combines custom validation (default) with optional Zod validators (opt-in).

When to Use Zod vs Custom Validation

Use Zod validators for:

Password strength requirements (uppercase, lowercase, numbers, special chars)
Conditional validation (different rules based on context)
Cross-field validation (one field depends on another)
Complex business logic requiring custom refinements
Advanced string parsing (dates, URLs, transformations)
Nested object/array validation

Use custom validation for:

Simple min/max length checks
Simple regex patterns (email, UUID, username)
Basic enum values (status, type fields)
Basic type checking (string, number, boolean)
Foreign key references
Most standard columns (enabled, createdDate, etc.)

How Hybrid Validation Works

Custom validation is default: All existing schemas use custom validation
Zod is opt-in: Add zodValidator field to any column to use Zod
No breaking changes: Existing code continues to work unchanged
Validation precedence: When zodValidator is present, Zod is used; otherwise custom validation runs

Adding Zod Validators to Columns

Step 1: Import or create a Zod validator

import { passwordStrengthValidator } from '../validation/zodValidators';

Step 2: Add zodValidator field to column definition

// Before (custom validation)
password: {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
},

// After (Zod validation)
password: {
  type: 'string',
  minLength: 8,  // Still useful for documentation
  maxLength: 100,
  name: 'password',
  typename: 'password',
  zodValidator: passwordStrengthValidator,  // Zod takes precedence
},

Important: Keep type, minLength, maxLength etc. even when using Zod - they serve as documentation and fallback.

Creating Custom Zod Validators

Example validators are in src/validation/zodValidators.ts:

// Simple password strength validator
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

// Reusable validator factory
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        try {
          const url = new URL(val);
          return allowedDomains.some((domain) =>
            url.hostname === domain || url.hostname.endsWith(`.${domain}`)
          );
        } catch {
          return false;
        }
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

Best Practices

1. Start simple, adopt gradually:

Don't migrate everything to Zod at once
Use Zod only where complexity justifies it
Keep custom validation for simple cases

2. Reuse validators:

Create validator library in zodValidators.ts
Export reusable validators for common patterns
Use factory functions for configurable validators

3. Maintain documentation fields:

Keep minLength, maxLength, values etc. for documentation
These fields help developers understand constraints without reading Zod code
Serves as fallback if Zod validator is removed

4. Error messages:

Provide clear, user-friendly error messages in Zod refinements
Zod errors are automatically converted to ValidationError format
Users see the same error structure regardless of validation method

5. Type safety:

Use z.ZodType<unknown> for the zodValidator field type
TypeScript ensures Zod validators are properly typed
Validation happens at runtime, types are enforced at compile time

Migration Path

Gradual adoption recommended:

Phase 1: Use custom validation for all schemas (current state for most schemas)
Phase 2: Add Zod validators to complex cases (passwords, emails with strict rules)
Phase 3: Evaluate if simple cases benefit from Zod (probably not)
Phase 4: Consider full Zod migration only if benefits are clear

No forced migration: Custom validation remains fully supported and is appropriate for most use cases.

Schema Column Type Definition

type SchemaColumn = {
  // ... existing fields ...

  /**
   * Optional Zod validator for complex validation logic.
   * When present, Zod validation is used instead of custom validation.
   * Allows opt-in to Zod for complex cases while maintaining custom validation as default.
   */
  zodValidator?: z.ZodType<unknown>;
};

Schema Aggregation

Access schemas:

import { schemas, getSchema, getAllSchemas } from 'cwc-schema';

// Get specific schema by name
const userSchema = getSchema('user');

// Get all schemas as array
const allSchemas = getAllSchemas();

// Access organized by type
const projectSchema = schemas.tables.project;

Helper functions:

getSchema(name: string): Schema | undefined - Find schema by name
getAllSchemas(): Schema[] - Get all schemas (tables + views)
validateAlphabeticalOrder(): void - Throws if schemas not alphabetically ordered

Alphabetical Ordering Requirement

Critical: All table schemas MUST be alphabetically ordered in src/index.ts

Enforcement:

Call validateAlphabeticalOrder() in tests
Throws error with expected vs actual order if violated

Rationale:

Prevents merge conflicts
Makes finding schemas easier
Ensures consistency across the codebase

Column Type Semantic Categories (typename)

Common typenames:

pkid - Primary key or foreign key integer
uuid - UUID v4 identifier (36 chars)
email - Email address
username - Username field
password - Password hash
deviceId - Device UUID
foreignKey - Foreign key reference
boolean - Boolean/TINYINT field
createdDate, modifiedDate, loginDate - Timestamp fields
string - Generic string field
text - Long text field (TEXT type)

Purpose:

Groups similar columns across tables
Enables generic tooling (e.g., admin UI knows how to render 'email' fields)
Self-documenting schema

Regex Patterns

Defined in src/validation/regexPatterns.ts:

EMAIL_REGEX - Email address validation
UUID_REGEX - UUID v4 format
USERNAME_REGEX - Alphanumeric + underscores, 4-100 chars
CONFIRMATION_CODE_REGEX - 6-character codes
PROJECT_ID_REGEX - URL-friendly project identifiers
FILENAME_REGEX - Valid filenames

Usage:

import { EMAIL_REGEX } from 'cwc-schema';

const emailColumn: SchemaColumn = {
  type: 'string',
  regex: EMAIL_REGEX,
  // ...
};

Future Enhancements

Potential future features (not implemented yet):

SQL Generation: Generate CREATE TABLE statements from schema
Type Generation: Generate cwc-types from schema (single source of truth)
Migration Diffing: Compare schema versions to generate migration SQL
Schema Validation: Validate schema matches actual database structure
Admin UI Generation: Auto-generate CRUD interfaces from schema
API Documentation: Generate API docs from schema metadata

Related Packages

Consumed By:

Backend microservices (cwc-api, cwc-sql, cwc-auth) for runtime validation
Future admin tools and generic CRUD interfaces

Depends On:

None (zero runtime dependencies by design)

Related:

cwc-database: SQL scripts are source of truth; schema mirrors them
cwc-types: Provides compile-time types; schema provides runtime validation

packages/cwc-schema/package.json

3 versions

Version 1

{
  "name": "cwc-schema",
  "version": "1.0.0",
  "description": "Database schema definitions with validation rules for CWC application",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "schema", "validation", "database"],
  "author": "",
  "license": "UNLICENSED",
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 2

{
  "name": "cwc-schema",
  "version": "1.0.0",
  "description": "Database schema definitions with validation rules for CWC application",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "schema", "validation", "database"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

Version 3 (latest)

{
  "name": "cwc-schema",
  "version": "1.0.0",
  "description": "Database schema definitions with validation rules for CWC application",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "typecheck": "tsc --noEmit"
  },
  "keywords": ["cwc", "schema", "validation", "database"],
  "author": "",
  "license": "UNLICENSED",
  "dependencies": {
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

packages/cwc-schema/src/columnTypes.ts

5 versions

Version 1

'use strict';

import { SchemaColumn } from './types.js';
import {
  EMAIL_REGEX,
  UUID_REGEX,
  USERNAME_REGEX,
  CONFIRMATION_CODE_REGEX,
  PROJECT_ID_REGEX,
  FILENAME_REGEX,
} from './validation/regexPatterns.js';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key (auto-increment integer, always positive)
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
  // maxValue omitted = unlimited
};

// Boolean (TINYINT in database)
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps (DATETIME in database, stored as ISO string)
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

export const loginDate: SchemaColumn = {
  type: 'string',
  name: 'loginDate',
  typename: 'loginDate',
};

// UUID identifier (36 characters with hyphens)
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// Email address (VARCHAR 45)
export const email: SchemaColumn = {
  type: 'string',
  minLength: 5,
  maxLength: 45,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

// Username (VARCHAR 100 - standard length)
export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 100,
  regex: USERNAME_REGEX,
  name: 'username',
  typename: 'username',
};

// Admin username (VARCHAR 25 - shorter for admin accounts)
export const adminUsername: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  regex: USERNAME_REGEX,
  name: 'adminUsername',
  typename: 'adminUsername',
};

// Password hash (VARCHAR 100 - bcrypt/argon2 hash)
export const password: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
};

// Device ID (UUID format, VARCHAR 36)
export const deviceId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'deviceId',
  typename: 'deviceId',
};

// Email verification ID (UUID format, VARCHAR 36)
export const emailVerificationId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'emailVerificationId',
  typename: 'emailVerificationId',
};

// Email confirmation code (6 character alphanumeric)
export const confirmationCode: SchemaColumn = {
  type: 'string',
  minLength: 6,
  maxLength: 6,
  regex: CONFIRMATION_CODE_REGEX,
  name: 'confirmationCode',
  typename: 'confirmationCode',
};

// Email confirmed status
export const emailConfirmed: SchemaColumn = {
  type: 'boolean',
  name: 'emailConfirmed',
  typename: 'emailConfirmed',
};

// Project ID (VARCHAR 150, URL-friendly identifier)
export const projectId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 150,
  regex: PROJECT_ID_REGEX,
  name: 'projectId',
  typename: 'projectId',
};

// Filename (VARCHAR 50)
export const filename: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  regex: FILENAME_REGEX,
  name: 'filename',
  typename: 'filename',
};

// OTP Secret for 2FA (VARCHAR 30)
export const otpSecret: SchemaColumn = {
  type: 'string',
  minLength: 16,
  maxLength: 30,
  name: 'otpSecret',
  typename: 'otpSecret',
};

// OTP Validated status
export const otpValidated: SchemaColumn = {
  type: 'boolean',
  name: 'otpValidated',
  typename: 'otpValidated',
};

// Published status
export const published: SchemaColumn = {
  type: 'boolean',
  name: 'published',
  typename: 'published',
};

// Dismissed status (for error logs)
export const dismissed: SchemaColumn = {
  type: 'boolean',
  name: 'dismissed',
  typename: 'dismissed',
};

// Enabled status (soft delete flag)
export const enabled: SchemaColumn = {
  type: 'boolean',
  name: 'enabled',
  typename: 'enabled',
};

// Display index for ordering (INT)
export const displayIndex: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'displayIndex',
  typename: 'displayIndex',
};

// Image dimensions (INT)
export const height: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'height',
  typename: 'height',
};

export const width: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'width',
  typename: 'width',
};

// Short message/description (VARCHAR 200)
export const shortMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'message',
  typename: 'shortMessage',
};

// Medium message (VARCHAR 500)
export const mediumMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 500,
  name: 'message',
  typename: 'mediumMessage',
};

// Description field (VARCHAR 200)
export const description: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'description',
  typename: 'description',
};

// Long text field (TEXT)
export const text: SchemaColumn = {
  type: 'string',
  minLength: 1,
  name: 'text',
  typename: 'text',
};

// Code location (VARCHAR 200)
export const codeLocation: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'codeLocation',
  typename: 'codeLocation',
};

// Service name (VARCHAR 75)
export const serviceName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 75,
  name: 'serviceName',
  typename: 'serviceName',
};

// Feature flag ID (VARCHAR 50)
export const featureFlagId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  name: 'featureFlagId',
  typename: 'featureFlagId',
};

// MIME type (VARCHAR 100)
export const mimeType: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 100,
  name: 'mimeType',
  typename: 'mimeType',
};

// Reaction name (VARCHAR 25)
export const reactionName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 25,
  name: 'reactionName',
  typename: 'reactionName',
};

// Attempt counters (INT)
export const attemptCount: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'attempts',
  typename: 'attemptCount',
};

Version 2

'use strict';

import { SchemaColumn } from './types';
import {
  EMAIL_REGEX,
  UUID_REGEX,
  USERNAME_REGEX,
  CONFIRMATION_CODE_REGEX,
  PROJECT_ID_REGEX,
  FILENAME_REGEX,
} from './validation/regexPatterns';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key (auto-increment integer, always positive)
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  minValue: 0,
  // maxValue omitted = unlimited
};

// Boolean (TINYINT in database)
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps (DATETIME in database, stored as ISO string)
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

export const loginDate: SchemaColumn = {
  type: 'string',
  name: 'loginDate',
  typename: 'loginDate',
};

// UUID identifier (36 characters with hyphens)
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// Email address (VARCHAR 45)
export const email: SchemaColumn = {
  type: 'string',
  minLength: 5,
  maxLength: 45,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

// Username (VARCHAR 100 - standard length)
export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 100,
  regex: USERNAME_REGEX,
  name: 'username',
  typename: 'username',
};

// Admin username (VARCHAR 25 - shorter for admin accounts)
export const adminUsername: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  regex: USERNAME_REGEX,
  name: 'adminUsername',
  typename: 'adminUsername',
};

// Password hash (VARCHAR 100 - bcrypt/argon2 hash)
export const password: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
};

// Device ID (UUID format, VARCHAR 36)
export const deviceId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'deviceId',
  typename: 'deviceId',
};

// Email verification ID (UUID format, VARCHAR 36)
export const emailVerificationId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'emailVerificationId',
  typename: 'emailVerificationId',
};

// Email confirmation code (6 character alphanumeric)
export const confirmationCode: SchemaColumn = {
  type: 'string',
  minLength: 6,
  maxLength: 6,
  regex: CONFIRMATION_CODE_REGEX,
  name: 'confirmationCode',
  typename: 'confirmationCode',
};

// Email confirmed status
export const emailConfirmed: SchemaColumn = {
  type: 'boolean',
  name: 'emailConfirmed',
  typename: 'emailConfirmed',
};

// Project ID (VARCHAR 150, URL-friendly identifier)
export const projectId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 150,
  regex: PROJECT_ID_REGEX,
  name: 'projectId',
  typename: 'projectId',
};

// Filename (VARCHAR 50)
export const filename: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  regex: FILENAME_REGEX,
  name: 'filename',
  typename: 'filename',
};

// OTP Secret for 2FA (VARCHAR 30)
export const otpSecret: SchemaColumn = {
  type: 'string',
  minLength: 16,
  maxLength: 30,
  name: 'otpSecret',
  typename: 'otpSecret',
};

// OTP Validated status
export const otpValidated: SchemaColumn = {
  type: 'boolean',
  name: 'otpValidated',
  typename: 'otpValidated',
};

// Published status
export const published: SchemaColumn = {
  type: 'boolean',
  name: 'published',
  typename: 'published',
};

// Dismissed status (for error logs)
export const dismissed: SchemaColumn = {
  type: 'boolean',
  name: 'dismissed',
  typename: 'dismissed',
};

// Enabled status (soft delete flag)
export const enabled: SchemaColumn = {
  type: 'boolean',
  name: 'enabled',
  typename: 'enabled',
};

// Display index for ordering (INT)
export const displayIndex: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'displayIndex',
  typename: 'displayIndex',
};

// Image dimensions (INT)
export const height: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'height',
  typename: 'height',
};

export const width: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'width',
  typename: 'width',
};

// Short message/description (VARCHAR 200)
export const shortMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'message',
  typename: 'shortMessage',
};

// Medium message (VARCHAR 500)
export const mediumMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 500,
  name: 'message',
  typename: 'mediumMessage',
};

// Description field (VARCHAR 200)
export const description: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'description',
  typename: 'description',
};

// Long text field (TEXT)
export const text: SchemaColumn = {
  type: 'string',
  minLength: 1,
  name: 'text',
  typename: 'text',
};

// Code location (VARCHAR 200)
export const codeLocation: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'codeLocation',
  typename: 'codeLocation',
};

// Service name (VARCHAR 75)
export const serviceName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 75,
  name: 'serviceName',
  typename: 'serviceName',
};

// Feature flag ID (VARCHAR 50)
export const featureFlagId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  name: 'featureFlagId',
  typename: 'featureFlagId',
};

// MIME type (VARCHAR 100)
export const mimeType: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 100,
  name: 'mimeType',
  typename: 'mimeType',
};

// Reaction name (VARCHAR 25)
export const reactionName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 25,
  name: 'reactionName',
  typename: 'reactionName',
};

// Attempt counters (INT)
export const attemptCount: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'attempts',
  typename: 'attemptCount',
};

Version 3

'use strict';

import { SchemaColumn } from './types';
import {
  EMAIL_REGEX,
  UUID_REGEX,
  USERNAME_REGEX,
  CONFIRMATION_CODE_REGEX,
  PROJECT_ID_REGEX,
  FILENAME_REGEX,
} from './validation/regexPatterns';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key (auto-increment integer, database-managed)
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  // No validation constraints - database auto-increment handles this
};

// Boolean (TINYINT in database)
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps (DATETIME in database, stored as ISO string)
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

export const loginDate: SchemaColumn = {
  type: 'string',
  name: 'loginDate',
  typename: 'loginDate',
};

// UUID identifier (36 characters with hyphens)
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// Email address (VARCHAR 45)
export const email: SchemaColumn = {
  type: 'string',
  minLength: 5,
  maxLength: 45,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

// Username (VARCHAR 100 - standard length)
export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 100,
  regex: USERNAME_REGEX,
  name: 'username',
  typename: 'username',
};

// Admin username (VARCHAR 25 - shorter for admin accounts)
export const adminUsername: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  regex: USERNAME_REGEX,
  name: 'adminUsername',
  typename: 'adminUsername',
};

// Password hash (VARCHAR 100 - bcrypt/argon2 hash)
export const password: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
};

// Device ID (UUID format, VARCHAR 36)
export const deviceId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'deviceId',
  typename: 'deviceId',
};

// Email verification ID (UUID format, VARCHAR 36)
export const emailVerificationId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'emailVerificationId',
  typename: 'emailVerificationId',
};

// Email confirmation code (6 character alphanumeric)
export const confirmationCode: SchemaColumn = {
  type: 'string',
  minLength: 6,
  maxLength: 6,
  regex: CONFIRMATION_CODE_REGEX,
  name: 'confirmationCode',
  typename: 'confirmationCode',
};

// Email confirmed status
export const emailConfirmed: SchemaColumn = {
  type: 'boolean',
  name: 'emailConfirmed',
  typename: 'emailConfirmed',
};

// Project ID (VARCHAR 150, URL-friendly identifier)
export const projectId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 150,
  regex: PROJECT_ID_REGEX,
  name: 'projectId',
  typename: 'projectId',
};

// Filename (VARCHAR 50)
export const filename: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  regex: FILENAME_REGEX,
  name: 'filename',
  typename: 'filename',
};

// OTP Secret for 2FA (VARCHAR 30)
export const otpSecret: SchemaColumn = {
  type: 'string',
  minLength: 16,
  maxLength: 30,
  name: 'otpSecret',
  typename: 'otpSecret',
};

// OTP Validated status
export const otpValidated: SchemaColumn = {
  type: 'boolean',
  name: 'otpValidated',
  typename: 'otpValidated',
};

// Published status
export const published: SchemaColumn = {
  type: 'boolean',
  name: 'published',
  typename: 'published',
};

// Dismissed status (for error logs)
export const dismissed: SchemaColumn = {
  type: 'boolean',
  name: 'dismissed',
  typename: 'dismissed',
};

// Enabled status (soft delete flag)
export const enabled: SchemaColumn = {
  type: 'boolean',
  name: 'enabled',
  typename: 'enabled',
};

// Display index for ordering (INT)
export const displayIndex: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'displayIndex',
  typename: 'displayIndex',
};

// Image dimensions (INT)
export const height: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'height',
  typename: 'height',
};

export const width: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'width',
  typename: 'width',
};

// Short message/description (VARCHAR 200)
export const shortMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'message',
  typename: 'shortMessage',
};

// Medium message (VARCHAR 500)
export const mediumMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 500,
  name: 'message',
  typename: 'mediumMessage',
};

// Description field (VARCHAR 200)
export const description: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'description',
  typename: 'description',
};

// Long text field (TEXT)
export const text: SchemaColumn = {
  type: 'string',
  minLength: 1,
  name: 'text',
  typename: 'text',
};

// Code location (VARCHAR 200)
export const codeLocation: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'codeLocation',
  typename: 'codeLocation',
};

// Service name (VARCHAR 75)
export const serviceName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 75,
  name: 'serviceName',
  typename: 'serviceName',
};

// Feature flag ID (VARCHAR 50)
export const featureFlagId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  name: 'featureFlagId',
  typename: 'featureFlagId',
};

// MIME type (VARCHAR 100)
export const mimeType: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 100,
  name: 'mimeType',
  typename: 'mimeType',
};

// Reaction name (VARCHAR 25)
export const reactionName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 25,
  name: 'reactionName',
  typename: 'reactionName',
};

// Attempt counters (INT)
export const attemptCount: SchemaColumn = {
  type: 'number',
  minValue: 1,
  name: 'attempts',
  typename: 'attemptCount',
};

Version 4

'use strict';

import { SchemaColumn } from './types';
import {
  EMAIL_REGEX,
  UUID_REGEX,
  USERNAME_REGEX,
  CONFIRMATION_CODE_REGEX,
  PROJECT_ID_REGEX,
  FILENAME_REGEX,
} from './validation/regexPatterns';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key (auto-increment integer, database-managed)
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  // No validation constraints - database auto-increment handles this
};

// Boolean (TINYINT in database)
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps (DATETIME in database, stored as ISO string)
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

export const loginDate: SchemaColumn = {
  type: 'string',
  name: 'loginDate',
  typename: 'loginDate',
};

// UUID identifier (36 characters with hyphens)
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// Email address (VARCHAR 45)
export const email: SchemaColumn = {
  type: 'string',
  minLength: 5,
  maxLength: 45,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

// Username (VARCHAR 100 - standard length)
export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 100,
  regex: USERNAME_REGEX,
  name: 'username',
  typename: 'username',
};

// Admin username (VARCHAR 25 - shorter for admin accounts)
export const adminUsername: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  regex: USERNAME_REGEX,
  name: 'adminUsername',
  typename: 'adminUsername',
};

// Password hash (VARCHAR 100 - bcrypt/argon2 hash)
export const password: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
};

// Device ID (UUID format, VARCHAR 36)
export const deviceId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'deviceId',
  typename: 'deviceId',
};

// Email verification ID (UUID format, VARCHAR 36)
export const emailVerificationId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'emailVerificationId',
  typename: 'emailVerificationId',
};

// Email confirmation code (6 character alphanumeric)
export const confirmationCode: SchemaColumn = {
  type: 'string',
  minLength: 6,
  maxLength: 6,
  regex: CONFIRMATION_CODE_REGEX,
  name: 'confirmationCode',
  typename: 'confirmationCode',
};

// Email confirmed status
export const emailConfirmed: SchemaColumn = {
  type: 'boolean',
  name: 'emailConfirmed',
  typename: 'emailConfirmed',
};

// Project ID (VARCHAR 150, URL-friendly identifier)
export const projectId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 150,
  regex: PROJECT_ID_REGEX,
  name: 'projectId',
  typename: 'projectId',
};

// Filename (VARCHAR 50)
export const filename: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  regex: FILENAME_REGEX,
  name: 'filename',
  typename: 'filename',
};

// OTP Secret for 2FA (VARCHAR 30)
export const otpSecret: SchemaColumn = {
  type: 'string',
  minLength: 16,
  maxLength: 30,
  name: 'otpSecret',
  typename: 'otpSecret',
};

// OTP Validated status
export const otpValidated: SchemaColumn = {
  type: 'boolean',
  name: 'otpValidated',
  typename: 'otpValidated',
};

// Published status
export const published: SchemaColumn = {
  type: 'boolean',
  name: 'published',
  typename: 'published',
};

// Dismissed status (for error logs)
export const dismissed: SchemaColumn = {
  type: 'boolean',
  name: 'dismissed',
  typename: 'dismissed',
};

// Enabled status (soft delete flag)
export const enabled: SchemaColumn = {
  type: 'boolean',
  name: 'enabled',
  typename: 'enabled',
};

// Display index for ordering (INT)
export const displayIndex: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'displayIndex',
  typename: 'displayIndex',
};

// Image dimensions (INT)
export const height: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'height',
  typename: 'height',
};

export const width: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'width',
  typename: 'width',
};

// Short message/description (VARCHAR 200)
export const shortMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'message',
  typename: 'shortMessage',
};

// Medium message (VARCHAR 500)
export const mediumMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 500,
  name: 'message',
  typename: 'mediumMessage',
};

// Description field (VARCHAR 200)
export const description: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'description',
  typename: 'description',
};

// Long text field (TEXT)
export const text: SchemaColumn = {
  type: 'string',
  minLength: 1,
  name: 'text',
  typename: 'text',
};

// Code location (VARCHAR 200)
export const codeLocation: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'codeLocation',
  typename: 'codeLocation',
};

// Service name (VARCHAR 75)
export const serviceName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 75,
  name: 'serviceName',
  typename: 'serviceName',
};

// Feature flag ID (VARCHAR 50)
export const featureFlagId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  name: 'featureFlagId',
  typename: 'featureFlagId',
};

// MIME type (VARCHAR 100)
export const mimeType: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 100,
  name: 'mimeType',
  typename: 'mimeType',
};

// Reaction name (VARCHAR 25)
export const reactionName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 25,
  name: 'reactionName',
  typename: 'reactionName',
};

// Attempt counters (INT)
export const attemptCount: SchemaColumn = {
  type: 'number',
  minValue: 1,
  name: 'attempts',
  typename: 'attemptCount',
};

// Foreign key to user table
export const userPkId: SchemaColumn = {
  type: 'number',
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
};

// Foreign key to project table
export const projectPkId: SchemaColumn = {
  type: 'number',
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
};

// Foreign key to codingSession table
export const codingSessionPkId: SchemaColumn = {
  type: 'number',
  name: 'codingSessionPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
};

// Polymorphic foreign key (generic entity reference)
export const entityPkId: SchemaColumn = {
  type: 'number',
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
  // No specific foreignKey.table - polymorphic (could point to multiple tables)
};

// Login type (cwc, facebook, google)
export const loginType: SchemaColumn = {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
};

Version 5 (latest)

'use strict';

import { SchemaColumn } from './types';
import {
  EMAIL_REGEX,
  UUID_REGEX,
  USERNAME_REGEX,
  CONFIRMATION_CODE_REGEX,
  PROJECT_ID_REGEX,
  FILENAME_REGEX,
} from './validation/regexPatterns';

/**
 * Reusable Column Type Definitions
 *
 * These base column types are used throughout table schemas via spread syntax:
 * Example: userId: { ...uuid, name: 'userId' }
 */

// Primary key (auto-increment integer, database-managed)
export const pkid: SchemaColumn = {
  type: 'number',
  name: 'pkid',
  typename: 'pkid',
  // No validation constraints - database auto-increment handles this
};

// Boolean (TINYINT in database)
export const boolean: SchemaColumn = {
  type: 'boolean',
  name: 'boolean',
  typename: 'boolean',
};

// Timestamps (DATETIME in database, stored as ISO string)
export const createdDate: SchemaColumn = {
  type: 'string',
  name: 'createdDate',
  typename: 'createdDate',
};

export const modifiedDate: SchemaColumn = {
  type: 'string',
  name: 'modifiedDate',
  typename: 'modifiedDate',
};

export const loginDate: SchemaColumn = {
  type: 'string',
  name: 'loginDate',
  typename: 'loginDate',
};

// UUID identifier (36 characters with hyphens)
export const uuid: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'uuid',
  typename: 'uuid',
};

// Email address (VARCHAR 45)
export const email: SchemaColumn = {
  type: 'string',
  minLength: 5,
  maxLength: 45,
  regex: EMAIL_REGEX,
  name: 'email',
  typename: 'email',
};

// Username (VARCHAR 100 - standard length)
export const username: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 100,
  regex: USERNAME_REGEX,
  name: 'username',
  typename: 'username',
};

// Admin username (VARCHAR 25 - shorter for admin accounts)
export const adminUsername: SchemaColumn = {
  type: 'string',
  minLength: 4,
  maxLength: 25,
  regex: USERNAME_REGEX,
  name: 'adminUsername',
  typename: 'adminUsername',
};

// Password hash (VARCHAR 100 - bcrypt/argon2 hash)
export const password: SchemaColumn = {
  type: 'string',
  minLength: 8,
  maxLength: 100,
  name: 'password',
  typename: 'password',
};

// Device ID (UUID format, VARCHAR 36)
export const deviceId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'deviceId',
  typename: 'deviceId',
};

// Email verification ID (UUID format, VARCHAR 36)
export const emailVerificationId: SchemaColumn = {
  type: 'string',
  minLength: 36,
  maxLength: 36,
  regex: UUID_REGEX,
  name: 'emailVerificationId',
  typename: 'emailVerificationId',
};

// Email confirmation code (6 character alphanumeric)
export const confirmationCode: SchemaColumn = {
  type: 'string',
  minLength: 6,
  maxLength: 6,
  regex: CONFIRMATION_CODE_REGEX,
  name: 'confirmationCode',
  typename: 'confirmationCode',
};

// Email confirmed status
export const emailConfirmed: SchemaColumn = {
  type: 'boolean',
  name: 'emailConfirmed',
  typename: 'emailConfirmed',
};

// Project ID (VARCHAR 150, URL-friendly identifier)
export const projectId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 150,
  regex: PROJECT_ID_REGEX,
  name: 'projectId',
  typename: 'projectId',
};

// Filename (VARCHAR 50)
export const filename: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  regex: FILENAME_REGEX,
  name: 'filename',
  typename: 'filename',
};

// OTP Secret for 2FA (VARCHAR 30)
export const otpSecret: SchemaColumn = {
  type: 'string',
  minLength: 16,
  maxLength: 30,
  name: 'otpSecret',
  typename: 'otpSecret',
};

// OTP Validated status
export const otpValidated: SchemaColumn = {
  type: 'boolean',
  name: 'otpValidated',
  typename: 'otpValidated',
};

// Published status
export const published: SchemaColumn = {
  type: 'boolean',
  name: 'published',
  typename: 'published',
};

// Dismissed status (for error logs)
export const dismissed: SchemaColumn = {
  type: 'boolean',
  name: 'dismissed',
  typename: 'dismissed',
};

// Enabled status (soft delete flag)
export const enabled: SchemaColumn = {
  type: 'boolean',
  name: 'enabled',
  typename: 'enabled',
};

// Display index for ordering (INT)
export const displayIndex: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'displayIndex',
  typename: 'displayIndex',
};

// Image dimensions (INT)
export const height: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'height',
  typename: 'height',
};

export const width: SchemaColumn = {
  type: 'number',
  minValue: 0,
  name: 'width',
  typename: 'width',
};

// Short message/description (VARCHAR 200)
export const shortMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'message',
  typename: 'shortMessage',
};

// Medium message (VARCHAR 500)
export const mediumMessage: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 500,
  name: 'message',
  typename: 'mediumMessage',
};

// Description field (VARCHAR 200)
export const description: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'description',
  typename: 'description',
};

// Long text field (TEXT)
export const text: SchemaColumn = {
  type: 'string',
  minLength: 1,
  name: 'text',
  typename: 'text',
};

// Code location (VARCHAR 200)
export const codeLocation: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 200,
  name: 'codeLocation',
  typename: 'codeLocation',
};

// Service name (VARCHAR 75)
export const serviceName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 75,
  name: 'serviceName',
  typename: 'serviceName',
};

// Feature flag ID (VARCHAR 50)
export const featureFlagId: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 50,
  name: 'featureFlagId',
  typename: 'featureFlagId',
};

// MIME type (VARCHAR 100)
export const mimeType: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 100,
  name: 'mimeType',
  typename: 'mimeType',
};

// Reaction name (VARCHAR 25)
export const reactionName: SchemaColumn = {
  type: 'string',
  minLength: 1,
  maxLength: 25,
  name: 'reactionName',
  typename: 'reactionName',
};

// Attempt counters (INT)
export const attemptCount: SchemaColumn = {
  type: 'number',
  minValue: 1,
  name: 'attempts',
  typename: 'attemptCount',
};

// Foreign key to user table
export const userPkId: SchemaColumn = {
  type: 'number',
  name: 'userPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'user', column: 'userPkId' },
};

// Foreign key to project table
export const projectPkId: SchemaColumn = {
  type: 'number',
  name: 'projectPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'project', column: 'projectPkId' },
};

// Foreign key to codingSession table
export const codingSessionPkId: SchemaColumn = {
  type: 'number',
  name: 'codingSessionPkId',
  typename: 'foreignKey',
  foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
};

// Polymorphic foreign key (generic entity reference)
export const entityPkId: SchemaColumn = {
  type: 'number',
  name: 'entityPkId',
  typename: 'foreignKey',
  required: true,
  // No specific foreignKey.table - polymorphic (could point to multiple tables)
};

// Login type (cwc, facebook, google)
export const loginType: SchemaColumn = {
  type: 'string',
  typename: 'string',
  minLength: 3,
  maxLength: 25,
  values: ['cwc', 'facebook', 'google'],
  name: 'loginType',
};

packages/cwc-schema/src/index.ts

3 versions

Version 1

'use strict';

import { Schema } from './types.js';

// Import all table schemas (alphabetically)
import { abuseReportSchema } from './tables/abuseReport.js';
import { adminUserSchema } from './tables/adminUser.js';
import { adminUserJwtSchema } from './tables/adminUserJwt.js';
import { codingSessionSchema } from './tables/codingSession.js';
import { codingSessionAttachmentSchema } from './tables/codingSessionAttachment.js';
import { codingSessionContentSchema } from './tables/codingSessionContent.js';
import { commentSchema } from './tables/comment.js';
import { contentReportSchema } from './tables/contentReport.js';
import { emailVerifySchema } from './tables/emailVerify.js';
import { errorLogSchema } from './tables/errorLog.js';
import { featureFlagSchema } from './tables/featureFlag.js';
import { passwordResetInfoSchema } from './tables/passwordResetInfo.js';
import { projectSchema } from './tables/project.js';
import { reactionSchema } from './tables/reaction.js';
import { signupInfoSchema } from './tables/signupInfo.js';
import { tempJwtSchema } from './tables/tempJwt.js';
import { userSchema } from './tables/user.js';
import { userJwtSchema } from './tables/userJwt.js';

/**
 * Organized schema structure
 * Separates tables and views for better organization
 */
export const schemas = {
  tables: {
    abuseReport: abuseReportSchema,
    adminUser: adminUserSchema,
    adminUserJwt: adminUserJwtSchema,
    codingSession: codingSessionSchema,
    codingSessionAttachment: codingSessionAttachmentSchema,
    codingSessionContent: codingSessionContentSchema,
    comment: commentSchema,
    contentReport: contentReportSchema,
    emailVerify: emailVerifySchema,
    errorLog: errorLogSchema,
    featureFlag: featureFlagSchema,
    passwordResetInfo: passwordResetInfoSchema,
    project: projectSchema,
    reaction: reactionSchema,
    signupInfo: signupInfoSchema,
    tempJwt: tempJwtSchema,
    user: userSchema,
    userJwt: userJwtSchema,
  },
  views: {
    // Views will be added when create-views.sql is populated
  },
};

/**
 * Get all schemas as a flat array
 */
export const getAllSchemas = (): Schema[] => [
  ...(Object.values(schemas.tables) as Schema[]),
  ...(Object.values(schemas.views) as Schema[]),
];

/**
 * Get a specific schema by name
 */
export const getSchema = (name: string): Schema | undefined => {
  return getAllSchemas().find((schema) => schema.name === name);
};

/**
 * Validate that schemas are in alphabetical order
 * Call this in tests to ensure consistency
 */
export const validateAlphabeticalOrder = (): void => {
  const tableNames = Object.keys(schemas.tables);
  const sortedTableNames = [...tableNames].sort();
  if (JSON.stringify(tableNames) !== JSON.stringify(sortedTableNames)) {
    throw new Error(
      `Table schemas must be alphabetically ordered.\nExpected: ${sortedTableNames.join(', ')}\nActual: ${tableNames.join(', ')}`
    );
  }

  const viewNames = Object.keys(schemas.views);
  const sortedViewNames = [...viewNames].sort();
  if (JSON.stringify(viewNames) !== JSON.stringify(sortedViewNames)) {
    throw new Error(
      `View schemas must be alphabetically ordered.\nExpected: ${sortedViewNames.join(', ')}\nActual: ${viewNames.join(', ')}`
    );
  }
};

// Re-export types for convenience
export * from './types.js';
export * from './columnTypes.js';
export * from './validation/regexPatterns.js';

Version 2

'use strict';

import { Schema } from './types';

// Import all table schemas (alphabetically)
import { abuseReportSchema } from './tables/abuseReport';
import { adminUserSchema } from './tables/adminUser';
import { adminUserJwtSchema } from './tables/adminUserJwt';
import { codingSessionSchema } from './tables/codingSession';
import { codingSessionAttachmentSchema } from './tables/codingSessionAttachment';
import { codingSessionContentSchema } from './tables/codingSessionContent';
import { commentSchema } from './tables/comment';
import { contentReportSchema } from './tables/contentReport';
import { emailVerifySchema } from './tables/emailVerify';
import { errorLogSchema } from './tables/errorLog';
import { featureFlagSchema } from './tables/featureFlag';
import { passwordResetInfoSchema } from './tables/passwordResetInfo';
import { projectSchema } from './tables/project';
import { reactionSchema } from './tables/reaction';
import { signupInfoSchema } from './tables/signupInfo';
import { tempJwtSchema } from './tables/tempJwt';
import { userSchema } from './tables/user';
import { userJwtSchema } from './tables/userJwt';

/**
 * Organized schema structure
 * Separates tables and views for better organization
 */
export const schemas = {
  tables: {
    abuseReport: abuseReportSchema,
    adminUser: adminUserSchema,
    adminUserJwt: adminUserJwtSchema,
    codingSession: codingSessionSchema,
    codingSessionAttachment: codingSessionAttachmentSchema,
    codingSessionContent: codingSessionContentSchema,
    comment: commentSchema,
    contentReport: contentReportSchema,
    emailVerify: emailVerifySchema,
    errorLog: errorLogSchema,
    featureFlag: featureFlagSchema,
    passwordResetInfo: passwordResetInfoSchema,
    project: projectSchema,
    reaction: reactionSchema,
    signupInfo: signupInfoSchema,
    tempJwt: tempJwtSchema,
    user: userSchema,
    userJwt: userJwtSchema,
  },
  views: {
    // Views will be added when create-views.sql is populated
  },
};

/**
 * Get all schemas as a flat array
 */
export const getAllSchemas = (): Schema[] => [
  ...(Object.values(schemas.tables) as Schema[]),
  ...(Object.values(schemas.views) as Schema[]),
];

/**
 * Get a specific schema by name
 */
export const getSchema = (name: string): Schema | undefined => {
  return getAllSchemas().find((schema) => schema.name === name);
};

/**
 * Validate that schemas are in alphabetical order
 * Call this in tests to ensure consistency
 */
export const validateAlphabeticalOrder = (): void => {
  const tableNames = Object.keys(schemas.tables);
  const sortedTableNames = [...tableNames].sort();
  if (JSON.stringify(tableNames) !== JSON.stringify(sortedTableNames)) {
    throw new Error(
      `Table schemas must be alphabetically ordered.\nExpected: ${sortedTableNames.join(', ')}\nActual: ${tableNames.join(', ')}`
    );
  }

  const viewNames = Object.keys(schemas.views);
  const sortedViewNames = [...viewNames].sort();
  if (JSON.stringify(viewNames) !== JSON.stringify(sortedViewNames)) {
    throw new Error(
      `View schemas must be alphabetically ordered.\nExpected: ${sortedViewNames.join(', ')}\nActual: ${viewNames.join(', ')}`
    );
  }
};

// Re-export types for convenience
export * from './types';
export * from './columnTypes';
export * from './validation/regexPatterns';

Version 3 (latest)

'use strict';

import { Schema } from './types';

// Import all table schemas (alphabetically)
import { abuseReportSchema } from './tables/abuseReport';
import { adminUserSchema } from './tables/adminUser';
import { adminUserJwtSchema } from './tables/adminUserJwt';
import { codingSessionSchema } from './tables/codingSession';
import { codingSessionAttachmentSchema } from './tables/codingSessionAttachment';
import { codingSessionContentSchema } from './tables/codingSessionContent';
import { commentSchema } from './tables/comment';
import { contentReportSchema } from './tables/contentReport';
import { emailVerifySchema } from './tables/emailVerify';
import { errorLogSchema } from './tables/errorLog';
import { featureFlagSchema } from './tables/featureFlag';
import { passwordResetInfoSchema } from './tables/passwordResetInfo';
import { projectSchema } from './tables/project';
import { reactionSchema } from './tables/reaction';
import { signupInfoSchema } from './tables/signupInfo';
import { tempJwtSchema } from './tables/tempJwt';
import { userSchema } from './tables/user';
import { userJwtSchema } from './tables/userJwt';

/**
 * Organized schema structure
 * Separates tables and views for better organization
 */
export const schemas = {
  tables: {
    abuseReport: abuseReportSchema,
    adminUser: adminUserSchema,
    adminUserJwt: adminUserJwtSchema,
    codingSession: codingSessionSchema,
    codingSessionAttachment: codingSessionAttachmentSchema,
    codingSessionContent: codingSessionContentSchema,
    comment: commentSchema,
    contentReport: contentReportSchema,
    emailVerify: emailVerifySchema,
    errorLog: errorLogSchema,
    featureFlag: featureFlagSchema,
    passwordResetInfo: passwordResetInfoSchema,
    project: projectSchema,
    reaction: reactionSchema,
    signupInfo: signupInfoSchema,
    tempJwt: tempJwtSchema,
    user: userSchema,
    userJwt: userJwtSchema,
  },
  views: {
    // Views will be added when create-views.sql is populated
  },
};

/**
 * Get all schemas as a flat array
 */
export const getAllSchemas = (): Schema[] => [
  ...(Object.values(schemas.tables) as Schema[]),
  ...(Object.values(schemas.views) as Schema[]),
];

/**
 * Get a specific schema by name
 */
export const getSchema = (name: string): Schema | undefined => {
  return getAllSchemas().find((schema) => schema.name === name);
};

/**
 * Validate that schemas are in alphabetical order
 * Call this in tests to ensure consistency
 */
export const validateAlphabeticalOrder = (): void => {
  const tableNames = Object.keys(schemas.tables);
  const sortedTableNames = [...tableNames].sort();
  if (JSON.stringify(tableNames) !== JSON.stringify(sortedTableNames)) {
    throw new Error(
      `Table schemas must be alphabetically ordered.\nExpected: ${sortedTableNames.join(', ')}\nActual: ${tableNames.join(', ')}`
    );
  }

  const viewNames = Object.keys(schemas.views);
  const sortedViewNames = [...viewNames].sort();
  if (JSON.stringify(viewNames) !== JSON.stringify(sortedViewNames)) {
    throw new Error(
      `View schemas must be alphabetically ordered.\nExpected: ${sortedViewNames.join(', ')}\nActual: ${viewNames.join(', ')}`
    );
  }
};

// Re-export types for convenience
export * from './types';
export * from './columnTypes';
export * from './validation/regexPatterns';

packages/cwc-schema/src/tables/abuseReport.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, mediumMessage } from '../columnTypes.js';

export const abuseReportSchema: Schema = {
  name: 'abuseReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'abuseReportPkId',
  columns: {
    abuseReportPkId: { ...pkid, name: 'abuseReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    usernames: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 1000,
      name: 'usernames',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, mediumMessage } from '../columnTypes';

export const abuseReportSchema: Schema = {
  name: 'abuseReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'abuseReportPkId',
  columns: {
    abuseReportPkId: { ...pkid, name: 'abuseReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    usernames: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 1000,
      name: 'usernames',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  mediumMessage,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const abuseReportSchema: Schema = {
  name: 'abuseReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'abuseReportPkId',
  columns: {
    abuseReportPkId: { ...pkid, name: 'abuseReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    usernames: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 1000,
      name: 'usernames',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  mediumMessage,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const abuseReportSchema: Schema = {
  name: 'abuseReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'abuseReportPkId',
  columns: {
    abuseReportPkId: { ...pkid, name: 'abuseReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    usernames: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 1000,
      name: 'usernames',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

packages/cwc-schema/src/tables/adminUser.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, adminUsername, password } from '../columnTypes.js';

export const adminUserSchema: Schema = {
  name: 'adminUser',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserPkId',
  columns: {
    adminUserPkId: { ...pkid, name: 'adminUserPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUsername,
    password,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, adminUsername, password } from '../columnTypes';

export const adminUserSchema: Schema = {
  name: 'adminUser',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserPkId',
  columns: {
    adminUserPkId: { ...pkid, name: 'adminUserPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUsername,
    password,
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, adminUsername, password } from '../columnTypes';

export const adminUserSchema: Schema = {
  name: 'adminUser',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserPkId',
  columns: {
    adminUserPkId: { ...pkid, name: 'adminUserPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUsername,
    password,
  },
};

packages/cwc-schema/src/tables/adminUserJwt.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes.js';

export const adminUserJwtSchema: Schema = {
  name: 'adminUserJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserJwtPkId',
  columns: {
    adminUserJwtPkId: { ...pkid, name: 'adminUserJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUserJwtId: { ...uuid, name: 'adminUserJwtId' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const adminUserJwtSchema: Schema = {
  name: 'adminUserJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserJwtPkId',
  columns: {
    adminUserJwtPkId: { ...pkid, name: 'adminUserJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUserJwtId: { ...uuid, name: 'adminUserJwtId' },
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const adminUserJwtSchema: Schema = {
  name: 'adminUserJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'adminUserJwtPkId',
  columns: {
    adminUserJwtPkId: { ...pkid, name: 'adminUserJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    adminUserJwtId: { ...uuid, name: 'adminUserJwtId' },
  },
};

packages/cwc-schema/src/tables/codingSession.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, text, published } from '../columnTypes.js';

export const codingSessionSchema: Schema = {
  name: 'codingSession',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionPkId',
  columns: {
    codingSessionPkId: { ...pkid, name: 'codingSessionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    description: { ...text, name: 'description' },
    published,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, text, published } from '../columnTypes';

export const codingSessionSchema: Schema = {
  name: 'codingSession',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionPkId',
  columns: {
    codingSessionPkId: { ...pkid, name: 'codingSessionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    description: { ...text, name: 'description' },
    published,
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  published,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const codingSessionSchema: Schema = {
  name: 'codingSession',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionPkId',
  columns: {
    codingSessionPkId: { ...pkid, name: 'codingSessionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    description: { ...text, name: 'description' },
    published,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  published,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const codingSessionSchema: Schema = {
  name: 'codingSession',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionPkId',
  columns: {
    codingSessionPkId: { ...pkid, name: 'codingSessionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    description: { ...text, name: 'description' },
    published,
  },
};

packages/cwc-schema/src/tables/codingSessionAttachment.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  filename,
  mimeType,
  height,
  width,
} from '../columnTypes.js';

export const codingSessionAttachmentSchema: Schema = {
  name: 'codingSessionAttachment',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionAttachmentPkId',
  columns: {
    codingSessionAttachmentPkId: { ...pkid, name: 'codingSessionAttachmentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    codingSessionPkId: {
      ...pkid,
      name: 'codingSessionPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
    },
    filename,
    mimeType: {
      ...mimeType,
      values: ['image/png', 'image/jpg'],
    },
    height,
    width,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  filename,
  mimeType,
  height,
  width,
} from '../columnTypes';

export const codingSessionAttachmentSchema: Schema = {
  name: 'codingSessionAttachment',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionAttachmentPkId',
  columns: {
    codingSessionAttachmentPkId: { ...pkid, name: 'codingSessionAttachmentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    codingSessionPkId: {
      ...pkid,
      name: 'codingSessionPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
    },
    filename,
    mimeType: {
      ...mimeType,
      values: ['image/png', 'image/jpg'],
    },
    height,
    width,
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  filename,
  mimeType,
  height,
  width,
  userPkId,
  projectPkId,
  codingSessionPkId,
} from '../columnTypes';

export const codingSessionAttachmentSchema: Schema = {
  name: 'codingSessionAttachment',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionAttachmentPkId',
  columns: {
    codingSessionAttachmentPkId: { ...pkid, name: 'codingSessionAttachmentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    codingSessionPkId,
    filename,
    mimeType: {
      ...mimeType,
      values: ['image/png', 'image/jpg'],
    },
    height,
    width,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  filename,
  mimeType,
  height,
  width,
  userPkId,
  projectPkId,
  codingSessionPkId,
} from '../columnTypes';

export const codingSessionAttachmentSchema: Schema = {
  name: 'codingSessionAttachment',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionAttachmentPkId',
  columns: {
    codingSessionAttachmentPkId: { ...pkid, name: 'codingSessionAttachmentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    codingSessionPkId,
    filename,
    mimeType: {
      ...mimeType,
      values: ['image/png', 'image/jpg'],
    },
    height,
    width,
  },
};

packages/cwc-schema/src/tables/codingSessionContent.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, text, displayIndex } from '../columnTypes.js';

export const codingSessionContentSchema: Schema = {
  name: 'codingSessionContent',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionContentPkId',
  columns: {
    codingSessionContentPkId: { ...pkid, name: 'codingSessionContentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    contentType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['prompt', 'response', 'note', 'attachment'],
      name: 'contentType',
    },
    codingSessionPkId: {
      ...pkid,
      name: 'codingSessionPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
    },
    codingSessionAttachmentPkId: {
      ...pkid,
      name: 'codingSessionAttachmentPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSessionAttachment', column: 'codingSessionAttachmentPkId' },
    },
    displayIndex,
    text,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, text, displayIndex } from '../columnTypes';

export const codingSessionContentSchema: Schema = {
  name: 'codingSessionContent',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionContentPkId',
  columns: {
    codingSessionContentPkId: { ...pkid, name: 'codingSessionContentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    contentType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['prompt', 'response', 'note', 'attachment'],
      name: 'contentType',
    },
    codingSessionPkId: {
      ...pkid,
      name: 'codingSessionPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSession', column: 'codingSessionPkId' },
    },
    codingSessionAttachmentPkId: {
      ...pkid,
      name: 'codingSessionAttachmentPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSessionAttachment', column: 'codingSessionAttachmentPkId' },
    },
    displayIndex,
    text,
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  displayIndex,
  userPkId,
  projectPkId,
  codingSessionPkId,
} from '../columnTypes';

export const codingSessionContentSchema: Schema = {
  name: 'codingSessionContent',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionContentPkId',
  columns: {
    codingSessionContentPkId: { ...pkid, name: 'codingSessionContentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    contentType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['prompt', 'response', 'note', 'attachment'],
      name: 'contentType',
    },
    codingSessionPkId,
    codingSessionAttachmentPkId: {
      ...pkid,
      name: 'codingSessionAttachmentPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSessionAttachment', column: 'codingSessionAttachmentPkId' },
    },
    displayIndex,
    text,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  displayIndex,
  userPkId,
  projectPkId,
  codingSessionPkId,
} from '../columnTypes';

export const codingSessionContentSchema: Schema = {
  name: 'codingSessionContent',
  type: 'table',
  version: '1.0.0',
  pkid: 'codingSessionContentPkId',
  columns: {
    codingSessionContentPkId: { ...pkid, name: 'codingSessionContentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    contentType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['prompt', 'response', 'note', 'attachment'],
      name: 'contentType',
    },
    codingSessionPkId,
    codingSessionAttachmentPkId: {
      ...pkid,
      name: 'codingSessionAttachmentPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'codingSessionAttachment', column: 'codingSessionAttachmentPkId' },
    },
    displayIndex,
    text,
  },
};

packages/cwc-schema/src/tables/comment.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, text } from '../columnTypes.js';

export const commentSchema: Schema = {
  name: 'comment',
  type: 'table',
  version: '1.0.0',
  pkid: 'commentPkId',
  columns: {
    commentPkId: { ...pkid, name: 'commentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    text,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, text } from '../columnTypes';

export const commentSchema: Schema = {
  name: 'comment',
  type: 'table',
  version: '1.0.0',
  pkid: 'commentPkId',
  columns: {
    commentPkId: { ...pkid, name: 'commentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    text,
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const commentSchema: Schema = {
  name: 'comment',
  type: 'table',
  version: '1.0.0',
  pkid: 'commentPkId',
  columns: {
    commentPkId: { ...pkid, name: 'commentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId,
    userPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    text,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  text,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const commentSchema: Schema = {
  name: 'comment',
  type: 'table',
  version: '1.0.0',
  pkid: 'commentPkId',
  columns: {
    commentPkId: { ...pkid, name: 'commentPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId,
    userPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    text,
  },
};

packages/cwc-schema/src/tables/contentReport.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, mediumMessage } from '../columnTypes.js';

export const contentReportSchema: Schema = {
  name: 'contentReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'contentReportPkId',
  columns: {
    contentReportPkId: { ...pkid, name: 'contentReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, mediumMessage } from '../columnTypes';

export const contentReportSchema: Schema = {
  name: 'contentReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'contentReportPkId',
  columns: {
    contentReportPkId: { ...pkid, name: 'contentReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  mediumMessage,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const contentReportSchema: Schema = {
  name: 'contentReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'contentReportPkId',
  columns: {
    contentReportPkId: { ...pkid, name: 'contentReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  mediumMessage,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const contentReportSchema: Schema = {
  name: 'contentReport',
  type: 'table',
  version: '1.0.0',
  pkid: 'contentReportPkId',
  columns: {
    contentReportPkId: { ...pkid, name: 'contentReportPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    message: {
      ...mediumMessage,
      required: true,
    },
    status: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['submitted', 'investigation', 'dismissed', 'resolved', 'retracted'],
      name: 'status',
    },
  },
};

packages/cwc-schema/src/tables/emailVerify.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  confirmationCode,
  email,
  deviceId,
  emailVerificationId,
} from '../columnTypes.js';

export const emailVerifySchema: Schema = {
  name: 'emailVerify',
  type: 'table',
  version: '1.0.0',
  pkid: 'emailVerifyPkId',
  columns: {
    emailVerifyPkId: { ...pkid, name: 'emailVerifyPkId' },
    enabled,
    createdDate,
    modifiedDate,
    confirmationCode,
    email,
    deviceId,
    confirmed: {
      type: 'boolean',
      name: 'confirmed',
      typename: 'confirmed',
    },
    emailVerificationId,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  confirmationCode,
  email,
  deviceId,
  emailVerificationId,
} from '../columnTypes';

export const emailVerifySchema: Schema = {
  name: 'emailVerify',
  type: 'table',
  version: '1.0.0',
  pkid: 'emailVerifyPkId',
  columns: {
    emailVerifyPkId: { ...pkid, name: 'emailVerifyPkId' },
    enabled,
    createdDate,
    modifiedDate,
    confirmationCode,
    email,
    deviceId,
    confirmed: {
      type: 'boolean',
      name: 'confirmed',
      typename: 'confirmed',
    },
    emailVerificationId,
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  confirmationCode,
  email,
  deviceId,
  emailVerificationId,
} from '../columnTypes';

export const emailVerifySchema: Schema = {
  name: 'emailVerify',
  type: 'table',
  version: '1.0.0',
  pkid: 'emailVerifyPkId',
  columns: {
    emailVerifyPkId: { ...pkid, name: 'emailVerifyPkId' },
    enabled,
    createdDate,
    modifiedDate,
    confirmationCode,
    email,
    deviceId,
    confirmed: {
      type: 'boolean',
      name: 'confirmed',
      typename: 'confirmed',
    },
    emailVerificationId,
  },
};

packages/cwc-schema/src/tables/errorLog.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  serviceName,
  codeLocation,
  dismissed,
  shortMessage,
  text,
} from '../columnTypes.js';

export const errorLogSchema: Schema = {
  name: 'errorLog',
  type: 'table',
  version: '1.0.0',
  pkid: 'errorLogPkId',
  columns: {
    errorLogPkId: { ...pkid, name: 'errorLogPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    serviceName: {
      ...serviceName,
      values: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website'],
      required: true,
    },
    codeLocation: {
      ...codeLocation,
      required: true,
    },
    dismissed: {
      ...dismissed,
      required: true,
    },
    errorType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['error', 'info', 'warn', 'debug'],
      name: 'errorType',
    },
    errorMessage: {
      ...shortMessage,
      name: 'errorMessage',
      required: true,
    },
    error: { ...text, name: 'error' },
    stack: { ...text, name: 'stack' },
    data: { ...text, name: 'data' },
    request: { ...text, name: 'request' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  serviceName,
  codeLocation,
  dismissed,
  shortMessage,
  text,
} from '../columnTypes';

export const errorLogSchema: Schema = {
  name: 'errorLog',
  type: 'table',
  version: '1.0.0',
  pkid: 'errorLogPkId',
  columns: {
    errorLogPkId: { ...pkid, name: 'errorLogPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    serviceName: {
      ...serviceName,
      values: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website'],
      required: true,
    },
    codeLocation: {
      ...codeLocation,
      required: true,
    },
    dismissed: {
      ...dismissed,
      required: true,
    },
    errorType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['error', 'info', 'warn', 'debug'],
      name: 'errorType',
    },
    errorMessage: {
      ...shortMessage,
      name: 'errorMessage',
      required: true,
    },
    error: { ...text, name: 'error' },
    stack: { ...text, name: 'stack' },
    data: { ...text, name: 'data' },
    request: { ...text, name: 'request' },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  serviceName,
  codeLocation,
  dismissed,
  shortMessage,
  text,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const errorLogSchema: Schema = {
  name: 'errorLog',
  type: 'table',
  version: '1.0.0',
  pkid: 'errorLogPkId',
  columns: {
    errorLogPkId: { ...pkid, name: 'errorLogPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    serviceName: {
      ...serviceName,
      values: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website'],
      required: true,
    },
    codeLocation: {
      ...codeLocation,
      required: true,
    },
    dismissed: {
      ...dismissed,
      required: true,
    },
    errorType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['error', 'info', 'warn', 'debug'],
      name: 'errorType',
    },
    errorMessage: {
      ...shortMessage,
      name: 'errorMessage',
      required: true,
    },
    error: { ...text, name: 'error' },
    stack: { ...text, name: 'stack' },
    data: { ...text, name: 'data' },
    request: { ...text, name: 'request' },
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  serviceName,
  codeLocation,
  dismissed,
  shortMessage,
  text,
  userPkId,
  projectPkId,
} from '../columnTypes';

export const errorLogSchema: Schema = {
  name: 'errorLog',
  type: 'table',
  version: '1.0.0',
  pkid: 'errorLogPkId',
  columns: {
    errorLogPkId: { ...pkid, name: 'errorLogPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    projectPkId,
    serviceName: {
      ...serviceName,
      values: ['cwc-auth', 'cwc-api', 'cwc-sql', 'cwc-website'],
      required: true,
    },
    codeLocation: {
      ...codeLocation,
      required: true,
    },
    dismissed: {
      ...dismissed,
      required: true,
    },
    errorType: {
      type: 'string',
      typename: 'string',
      minLength: 4,
      maxLength: 25,
      values: ['error', 'info', 'warn', 'debug'],
      name: 'errorType',
    },
    errorMessage: {
      ...shortMessage,
      name: 'errorMessage',
      required: true,
    },
    error: { ...text, name: 'error' },
    stack: { ...text, name: 'stack' },
    data: { ...text, name: 'data' },
    request: { ...text, name: 'request' },
  },
};

packages/cwc-schema/src/tables/featureFlag.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  featureFlagId,
  serviceName,
  description,
} from '../columnTypes.js';

export const featureFlagSchema: Schema = {
  name: 'featureFlag',
  type: 'table',
  version: '1.0.0',
  pkid: 'featureFlagPkId',
  columns: {
    featureFlagPkId: { ...pkid, name: 'featureFlagPkId' },
    enabled,
    createdDate,
    modifiedDate,
    featureFlagType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['feature', 'system'],
      name: 'featureFlagType',
      required: true,
    },
    featureFlagId: {
      ...featureFlagId,
      required: true,
    },
    valueType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['boolean', 'number', 'string', 'object'],
      name: 'valueType',
      required: true,
    },
    value: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 200,
      name: 'value',
      required: true,
    },
    description,
    platform: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['all', 'web', 'android', 'ios', 'mobile'],
      name: 'platform',
    },
    serviceName: {
      ...serviceName,
      values: [
        'all',
        'frontend',
        'backend',
        'cwc-app',
        'cwc-sql',
        'cwc-auth',
        'cwc-api',
        'cwc-admin-api',
        'cwc-dashboard',
      ],
      required: true,
    },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  featureFlagId,
  serviceName,
  description,
} from '../columnTypes';

export const featureFlagSchema: Schema = {
  name: 'featureFlag',
  type: 'table',
  version: '1.0.0',
  pkid: 'featureFlagPkId',
  columns: {
    featureFlagPkId: { ...pkid, name: 'featureFlagPkId' },
    enabled,
    createdDate,
    modifiedDate,
    featureFlagType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['feature', 'system'],
      name: 'featureFlagType',
      required: true,
    },
    featureFlagId: {
      ...featureFlagId,
      required: true,
    },
    valueType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['boolean', 'number', 'string', 'object'],
      name: 'valueType',
      required: true,
    },
    value: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 200,
      name: 'value',
      required: true,
    },
    description,
    platform: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['all', 'web', 'android', 'ios', 'mobile'],
      name: 'platform',
    },
    serviceName: {
      ...serviceName,
      values: [
        'all',
        'frontend',
        'backend',
        'cwc-app',
        'cwc-sql',
        'cwc-auth',
        'cwc-api',
        'cwc-admin-api',
        'cwc-dashboard',
      ],
      required: true,
    },
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  featureFlagId,
  serviceName,
  description,
} from '../columnTypes';

export const featureFlagSchema: Schema = {
  name: 'featureFlag',
  type: 'table',
  version: '1.0.0',
  pkid: 'featureFlagPkId',
  columns: {
    featureFlagPkId: { ...pkid, name: 'featureFlagPkId' },
    enabled,
    createdDate,
    modifiedDate,
    featureFlagType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['feature', 'system'],
      name: 'featureFlagType',
      required: true,
    },
    featureFlagId: {
      ...featureFlagId,
      required: true,
    },
    valueType: {
      type: 'string',
      typename: 'string',
      minLength: 6,
      maxLength: 25,
      values: ['boolean', 'number', 'string', 'object'],
      name: 'valueType',
      required: true,
    },
    value: {
      type: 'string',
      typename: 'string',
      minLength: 1,
      maxLength: 200,
      name: 'value',
      required: true,
    },
    description,
    platform: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['all', 'web', 'android', 'ios', 'mobile'],
      name: 'platform',
    },
    serviceName: {
      ...serviceName,
      values: [
        'all',
        'frontend',
        'backend',
        'cwc-app',
        'cwc-sql',
        'cwc-auth',
        'cwc-api',
        'cwc-admin-api',
        'cwc-dashboard',
      ],
      required: true,
    },
  },
};

packages/cwc-schema/src/tables/passwordResetInfo.ts

5 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
} from '../columnTypes.js';

export const passwordResetInfoSchema: Schema = {
  name: 'passwordResetInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'passwordResetInfoPkId',
  columns: {
    passwordResetInfoPkId: { ...pkid, name: 'passwordResetInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    passwordResetAttempts: { ...attemptCount, name: 'passwordResetAttempts' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
} from '../columnTypes';

export const passwordResetInfoSchema: Schema = {
  name: 'passwordResetInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'passwordResetInfoPkId',
  columns: {
    passwordResetInfoPkId: { ...pkid, name: 'passwordResetInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    passwordResetAttempts: { ...attemptCount, name: 'passwordResetAttempts' },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
} from '../columnTypes';

export const passwordResetInfoSchema: Schema = {
  name: 'passwordResetInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'passwordResetInfoPkId',
  columns: {
    passwordResetInfoPkId: { ...pkid, name: 'passwordResetInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    passwordResetAttempts: { ...attemptCount, name: 'passwordResetAttempts' },
  },
};

Version 4

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
} from '../columnTypes';
import { passwordStrengthValidator } from '../validation/zodValidators';

export const passwordResetInfoSchema: Schema = {
  name: 'passwordResetInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'passwordResetInfoPkId',
  columns: {
    passwordResetInfoPkId: { ...pkid, name: 'passwordResetInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    username,
    password: {
      ...password,
      zodValidator: passwordStrengthValidator,
    },
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    passwordResetAttempts: { ...attemptCount, name: 'passwordResetAttempts' },
  },
};

Version 5 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
} from '../columnTypes';
import { passwordStrengthValidator } from '../validation/zodValidators';

export const passwordResetInfoSchema: Schema = {
  name: 'passwordResetInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'passwordResetInfoPkId',
  columns: {
    passwordResetInfoPkId: { ...pkid, name: 'passwordResetInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userPkId,
    username,
    password: {
      ...password,
      zodValidator: passwordStrengthValidator,
    },
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    passwordResetAttempts: { ...attemptCount, name: 'passwordResetAttempts' },
  },
};

packages/cwc-schema/src/tables/project.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, projectId } from '../columnTypes.js';

export const projectSchema: Schema = {
  name: 'project',
  type: 'table',
  version: '1.0.0',
  pkid: 'projectPkId',
  columns: {
    projectPkId: { ...pkid, name: 'projectPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectId,
    projectType: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 25,
      values: ['web', 'mobile', 'backend', 'ai'],
      name: 'projectType',
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, projectId } from '../columnTypes';

export const projectSchema: Schema = {
  name: 'project',
  type: 'table',
  version: '1.0.0',
  pkid: 'projectPkId',
  columns: {
    projectPkId: { ...pkid, name: 'projectPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectId,
    projectType: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 25,
      values: ['web', 'mobile', 'backend', 'ai'],
      name: 'projectType',
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, projectId, userPkId } from '../columnTypes';

export const projectSchema: Schema = {
  name: 'project',
  type: 'table',
  version: '1.0.0',
  pkid: 'projectPkId',
  columns: {
    projectPkId: { ...pkid, name: 'projectPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectId,
    projectType: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 25,
      values: ['web', 'mobile', 'backend', 'ai'],
      name: 'projectType',
    },
    userPkId,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, projectId, userPkId } from '../columnTypes';

export const projectSchema: Schema = {
  name: 'project',
  type: 'table',
  version: '1.0.0',
  pkid: 'projectPkId',
  columns: {
    projectPkId: { ...pkid, name: 'projectPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectId,
    projectType: {
      type: 'string',
      typename: 'string',
      minLength: 2,
      maxLength: 25,
      values: ['web', 'mobile', 'backend', 'ai'],
      name: 'projectType',
    },
    userPkId,
  },
};

packages/cwc-schema/src/tables/reaction.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, reactionName } from '../columnTypes.js';

export const reactionSchema: Schema = {
  name: 'reaction',
  type: 'table',
  version: '1.0.0',
  pkid: 'reactionPkId',
  columns: {
    reactionPkId: { ...pkid, name: 'reactionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    reactionName: {
      ...reactionName,
      values: ['love', 'funny', 'sad', 'wow', 'thumbs-up'],
    },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, reactionName } from '../columnTypes';

export const reactionSchema: Schema = {
  name: 'reaction',
  type: 'table',
  version: '1.0.0',
  pkid: 'reactionPkId',
  columns: {
    reactionPkId: { ...pkid, name: 'reactionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId: {
      ...pkid,
      name: 'projectPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'project', column: 'projectPkId' },
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    entityPkId: {
      ...pkid,
      name: 'entityPkId',
      typename: 'foreignKey',
      required: true,
    },
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    reactionName: {
      ...reactionName,
      values: ['love', 'funny', 'sad', 'wow', 'thumbs-up'],
    },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  reactionName,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const reactionSchema: Schema = {
  name: 'reaction',
  type: 'table',
  version: '1.0.0',
  pkid: 'reactionPkId',
  columns: {
    reactionPkId: { ...pkid, name: 'reactionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId,
    userPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    reactionName: {
      ...reactionName,
      values: ['love', 'funny', 'sad', 'wow', 'thumbs-up'],
    },
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  reactionName,
  userPkId,
  projectPkId,
  entityPkId,
} from '../columnTypes';

export const reactionSchema: Schema = {
  name: 'reaction',
  type: 'table',
  version: '1.0.0',
  pkid: 'reactionPkId',
  columns: {
    reactionPkId: { ...pkid, name: 'reactionPkId' },
    enabled,
    createdDate,
    modifiedDate,
    projectPkId,
    userPkId,
    entityPkId,
    entityType: {
      type: 'string',
      typename: 'string',
      minLength: 7,
      maxLength: 50,
      values: ['project', 'codingSession', 'codingSessionContent', 'codingSessionAttachment', 'comment'],
      name: 'entityType',
      required: true,
    },
    reactionName: {
      ...reactionName,
      values: ['love', 'funny', 'sad', 'wow', 'thumbs-up'],
    },
  },
};

packages/cwc-schema/src/tables/signupInfo.ts

5 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
} from '../columnTypes.js';

export const signupInfoSchema: Schema = {
  name: 'signupInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'signupInfoPkId',
  columns: {
    signupInfoPkId: { ...pkid, name: 'signupInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    loginType: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['cwc', 'facebook', 'google'],
      name: 'loginType',
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    signupAttempts: { ...attemptCount, name: 'signupAttempts' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
} from '../columnTypes';

export const signupInfoSchema: Schema = {
  name: 'signupInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'signupInfoPkId',
  columns: {
    signupInfoPkId: { ...pkid, name: 'signupInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    loginType: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['cwc', 'facebook', 'google'],
      name: 'loginType',
    },
    userPkId: {
      ...pkid,
      name: 'userPkId',
      typename: 'foreignKey',
      foreignKey: { table: 'user', column: 'userPkId' },
    },
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    signupAttempts: { ...attemptCount, name: 'signupAttempts' },
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
  loginType,
} from '../columnTypes';

export const signupInfoSchema: Schema = {
  name: 'signupInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'signupInfoPkId',
  columns: {
    signupInfoPkId: { ...pkid, name: 'signupInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    loginType,
    userPkId,
    username,
    password,
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    signupAttempts: { ...attemptCount, name: 'signupAttempts' },
  },
};

Version 4

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
  loginType,
} from '../columnTypes';
import { passwordStrengthValidator } from '../validation/zodValidators';

export const signupInfoSchema: Schema = {
  name: 'signupInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'signupInfoPkId',
  columns: {
    signupInfoPkId: { ...pkid, name: 'signupInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    loginType,
    userPkId,
    username,
    password: {
      ...password,
      zodValidator: passwordStrengthValidator,
    },
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    signupAttempts: { ...attemptCount, name: 'signupAttempts' },
  },
};

Version 5 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  password,
  email,
  emailVerificationId,
  emailConfirmed,
  deviceId,
  attemptCount,
  userPkId,
  loginType,
} from '../columnTypes';
import { passwordStrengthValidator } from '../validation/zodValidators';

export const signupInfoSchema: Schema = {
  name: 'signupInfo',
  type: 'table',
  version: '1.0.0',
  pkid: 'signupInfoPkId',
  columns: {
    signupInfoPkId: { ...pkid, name: 'signupInfoPkId' },
    enabled,
    createdDate,
    modifiedDate,
    loginType,
    userPkId,
    username,
    password: {
      ...password,
      zodValidator: passwordStrengthValidator,
    },
    email,
    emailVerificationId,
    emailConfirmed,
    deviceId,
    signupAttempts: { ...attemptCount, name: 'signupAttempts' },
  },
};

packages/cwc-schema/src/tables/tempJwt.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes.js';

export const tempJwtSchema: Schema = {
  name: 'tempJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'tempJwtPkId',
  columns: {
    tempJwtPkId: { ...pkid, name: 'tempJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    tempJwtId: { ...uuid, name: 'tempJwtId' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const tempJwtSchema: Schema = {
  name: 'tempJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'tempJwtPkId',
  columns: {
    tempJwtPkId: { ...pkid, name: 'tempJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    tempJwtId: { ...uuid, name: 'tempJwtId' },
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const tempJwtSchema: Schema = {
  name: 'tempJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'tempJwtPkId',
  columns: {
    tempJwtPkId: { ...pkid, name: 'tempJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    tempJwtId: { ...uuid, name: 'tempJwtId' },
  },
};

packages/cwc-schema/src/tables/user.ts

4 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  loginDate,
  password,
  email,
  emailConfirmed,
  deviceId,
  otpSecret,
  otpValidated,
} from '../columnTypes.js';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  version: '1.0.0',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    enabled,
    createdDate,
    modifiedDate,
    username,
    loginType: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['cwc', 'facebook', 'google'],
      name: 'loginType',
    },
    loginDate,
    password,
    email,
    emailConfirmed,
    deviceId,
    otpSecret,
    otpValidated,
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  loginDate,
  password,
  email,
  emailConfirmed,
  deviceId,
  otpSecret,
  otpValidated,
} from '../columnTypes';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  version: '1.0.0',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    enabled,
    createdDate,
    modifiedDate,
    username,
    loginType: {
      type: 'string',
      typename: 'string',
      minLength: 3,
      maxLength: 25,
      values: ['cwc', 'facebook', 'google'],
      name: 'loginType',
    },
    loginDate,
    password,
    email,
    emailConfirmed,
    deviceId,
    otpSecret,
    otpValidated,
  },
};

Version 3

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  loginDate,
  password,
  email,
  emailConfirmed,
  deviceId,
  otpSecret,
  otpValidated,
  loginType,
} from '../columnTypes';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  version: '1.0.0',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    enabled,
    createdDate,
    modifiedDate,
    username,
    loginType,
    loginDate,
    password,
    email,
    emailConfirmed,
    deviceId,
    otpSecret,
    otpValidated,
  },
};

Version 4 (latest)

'use strict';

import { Schema } from '../types';
import {
  pkid,
  enabled,
  createdDate,
  modifiedDate,
  username,
  loginDate,
  password,
  email,
  emailConfirmed,
  deviceId,
  otpSecret,
  otpValidated,
  loginType,
} from '../columnTypes';

export const userSchema: Schema = {
  name: 'user',
  type: 'table',
  version: '1.0.0',
  pkid: 'userPkId',
  columns: {
    userPkId: { ...pkid, name: 'userPkId' },
    enabled,
    createdDate,
    modifiedDate,
    username,
    loginType,
    loginDate,
    password,
    email,
    emailConfirmed,
    deviceId,
    otpSecret,
    otpValidated,
  },
};

packages/cwc-schema/src/tables/userJwt.ts

3 versions

Version 1

'use strict';

import { Schema } from '../types.js';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes.js';

export const userJwtSchema: Schema = {
  name: 'userJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'userJwtPkId',
  columns: {
    userJwtPkId: { ...pkid, name: 'userJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userJwtId: { ...uuid, name: 'userJwtId' },
  },
};

Version 2

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const userJwtSchema: Schema = {
  name: 'userJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'userJwtPkId',
  columns: {
    userJwtPkId: { ...pkid, name: 'userJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userJwtId: { ...uuid, name: 'userJwtId' },
  },
};

Version 3 (latest)

'use strict';

import { Schema } from '../types';
import { pkid, enabled, createdDate, modifiedDate, uuid } from '../columnTypes';

export const userJwtSchema: Schema = {
  name: 'userJwt',
  type: 'table',
  version: '1.0.0',
  pkid: 'userJwtPkId',
  columns: {
    userJwtPkId: { ...pkid, name: 'userJwtPkId' },
    enabled,
    createdDate,
    modifiedDate,
    userJwtId: { ...uuid, name: 'userJwtId' },
  },
};

packages/cwc-schema/src/types.ts

3 versions

Version 1

'use strict';

export type SchemaColumn = {
  /** Primitive JavaScript/SQL type */
  type: 'string' | 'number' | 'boolean' | 'object';

  /** Actual column name in database table */
  name: string;

  /** Semantic type category (e.g., 'uuid', 'email', 'phone') for validation/documentation */
  typename: string;

  /** Whether this column is required (true) or optional (false/undefined) */
  required?: boolean;

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  /** Allowed enum values for this column */
  values?: string[];

  // Number validation
  minValue?: number;
  /** Maximum value. If undefined, no maximum limit */
  maxValue?: number;

  /** Foreign key relationship metadata */
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };
};

export type Schema = {
  /** Table or view name */
  name: string;

  /** Schema type */
  type: 'table' | 'view';

  /** Schema version for migration tracking (optional) */
  version?: string;

  /** Primary key column name (undefined for views) */
  pkid: string | undefined;

  /** Column definitions */
  columns: Record<string, SchemaColumn>;
};

Version 2

'use strict';

import { z } from 'zod';

export type SchemaColumn = {
  /** Primitive JavaScript/SQL type */
  type: 'string' | 'number' | 'boolean' | 'object';

  /** Actual column name in database table */
  name: string;

  /** Semantic type category (e.g., 'uuid', 'email', 'phone') for validation/documentation */
  typename: string;

  /** Whether this column is required (true) or optional (false/undefined) */
  required?: boolean;

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  /** Allowed enum values for this column */
  values?: string[];

  // Number validation
  minValue?: number;
  /** Maximum value. If undefined, no maximum limit */
  maxValue?: number;

  /** Foreign key relationship metadata */
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };

  /**
   * Optional Zod validator for complex validation logic.
   * When present, Zod validation is used instead of custom validation.
   * Allows opt-in to Zod for complex cases while maintaining custom validation as default.
   */
  zodValidator?: z.ZodType<unknown>;
};

export type Schema = {
  /** Table or view name */
  name: string;

  /** Schema type */
  type: 'table' | 'view';

  /** Schema version for migration tracking (optional) */
  version?: string;

  /** Primary key column name (undefined for views) */
  pkid: string | undefined;

  /** Column definitions */
  columns: Record<string, SchemaColumn>;
};

Version 3 (latest)

'use strict';

import { z } from 'zod';

export type SchemaColumn = {
  /** Primitive JavaScript/SQL type */
  type: 'string' | 'number' | 'boolean' | 'object';

  /** Actual column name in database table */
  name: string;

  /** Semantic type category (e.g., 'uuid', 'email', 'phone') for validation/documentation */
  typename: string;

  /** Whether this column is required (true) or optional (false/undefined) */
  required?: boolean;

  // String validation
  minLength?: number;
  maxLength?: number;
  regex?: RegExp;
  /** Allowed enum values for this column */
  values?: string[];

  // Number validation
  minValue?: number;
  /** Maximum value. If undefined, no maximum limit */
  maxValue?: number;

  /** Foreign key relationship metadata */
  foreignKey?: {
    table: string;
    column: string;
    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
  };

  /**
   * Optional Zod validator for complex validation logic.
   * When present, Zod validation is used instead of custom validation.
   * Allows opt-in to Zod for complex cases while maintaining custom validation as default.
   */
  zodValidator?: z.ZodType<unknown>;
};

export type Schema = {
  /** Table or view name */
  name: string;

  /** Schema type */
  type: 'table' | 'view';

  /** Schema version for migration tracking (optional) */
  version?: string;

  /** Primary key column name (undefined for views) */
  pkid: string | undefined;

  /** Column definitions */
  columns: Record<string, SchemaColumn>;
};

packages/cwc-schema/src/validation/regexPatterns.ts

2 versions

Version 1

'use strict';

/**
 * Email validation regex
 * Note: Basic validation - may need enhancement for full RFC 5322 compliance
 */
export const EMAIL_REGEX = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,})+$/;

/**
 * UUID v4 validation (36 characters with hyphens)
 * Used for: deviceId, emailVerificationId, various JWT IDs
 */
export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

/**
 * Username validation
 * Alphanumeric plus underscores, 4-100 characters
 */
export const USERNAME_REGEX = /^[a-zA-Z0-9_]{4,100}$/;

/**
 * Confirmation code validation (6 characters)
 * Used for email verification
 */
export const CONFIRMATION_CODE_REGEX = /^[A-Z0-9]{6}$/;

/**
 * Project ID validation (alphanumeric with hyphens, up to 150 characters)
 * Allows URL-friendly identifiers
 */
export const PROJECT_ID_REGEX = /^[a-zA-Z0-9-]{1,150}$/;

/**
 * Filename validation (up to 50 characters, alphanumeric plus common file chars)
 * Allows letters, numbers, dots, dashes, underscores
 */
export const FILENAME_REGEX = /^[a-zA-Z0-9._-]{1,50}$/;

Version 2 (latest)

'use strict';

/**
 * Email validation regex
 * Note: Basic validation - may need enhancement for full RFC 5322 compliance
 */
export const EMAIL_REGEX = /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,})+$/;

/**
 * UUID v4 validation (36 characters with hyphens)
 * Used for: deviceId, emailVerificationId, various JWT IDs
 */
export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

/**
 * Username validation
 * Alphanumeric plus underscores, 4-100 characters
 */
export const USERNAME_REGEX = /^[a-zA-Z0-9_]{4,100}$/;

/**
 * Confirmation code validation (6 characters)
 * Used for email verification
 */
export const CONFIRMATION_CODE_REGEX = /^[A-Z0-9]{6}$/;

/**
 * Project ID validation (alphanumeric with hyphens, up to 150 characters)
 * Allows URL-friendly identifiers
 */
export const PROJECT_ID_REGEX = /^[a-zA-Z0-9-]{1,150}$/;

/**
 * Filename validation (up to 50 characters, alphanumeric plus common file chars)
 * Allows letters, numbers, dots, dashes, underscores
 */
export const FILENAME_REGEX = /^[a-zA-Z0-9._-]{1,50}$/;

packages/cwc-schema/src/validation/validator.ts

4 versions

Version 1

'use strict';

import { Schema, SchemaColumn } from '../types.js';

export type ValidationError = {
  field: string;
  message: string;
  value?: unknown;
};

export type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];
};

/**
 * Validate a single column value against its schema definition
 */
export const validateColumn = (
  value: unknown,
  column: SchemaColumn,
  fieldName?: string
): ValidationResult => {
  const errors: ValidationError[] = [];
  const field = fieldName || column.name;

  // Check required
  if (column.required && (value === null || value === undefined)) {
    errors.push({
      field,
      message: `Field '${field}' is required`,
      value,
    });
    return { valid: false, errors };
  }

  // If value is null/undefined and not required, skip further validation
  if (value === null || value === undefined) {
    return { valid: true, errors: [] };
  }

  // Type validation
  const actualType = typeof value;
  let expectedType = column.type;
  if (expectedType === 'object') expectedType = 'object';

  if (actualType !== expectedType) {
    errors.push({
      field,
      message: `Field '${field}' must be of type ${column.type}, got ${actualType}`,
      value,
    });
    return { valid: false, errors };
  }

  // String validation
  if (column.type === 'string' && typeof value === 'string') {
    if (column.minLength !== undefined && value.length < column.minLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.maxLength !== undefined && value.length > column.maxLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.regex && !column.regex.test(value)) {
      errors.push({
        field,
        message: `Field '${field}' does not match required format`,
        value,
      });
    }

    if (column.values && !column.values.includes(value)) {
      errors.push({
        field,
        message: `Field '${field}' must be one of: [${column.values.join(', ')}], got '${value}'`,
        value,
      });
    }
  }

  // Number validation
  if (column.type === 'number' && typeof value === 'number') {
    if (column.minValue !== undefined && value < column.minValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minValue}, got ${value}`,
        value,
      });
    }

    if (column.maxValue !== undefined && value > column.maxValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxValue}, got ${value}`,
        value,
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate an entire entity against its schema
 */
export const validateEntity = (data: Record<string, unknown>, schema: Schema): ValidationResult => {
  const errors: ValidationError[] = [];

  // Validate each column in the schema
  for (const [columnName, columnDef] of Object.entries(schema.columns)) {
    const value = data[columnName];
    const result = validateColumn(value, columnDef, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  // Check for unexpected fields
  for (const key of Object.keys(data)) {
    if (!schema.columns[key]) {
      errors.push({
        field: key,
        message: `Unexpected field '${key}' not defined in schema '${schema.name}'`,
        value: data[key],
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate a partial entity (useful for updates where not all fields are provided)
 */
export const validatePartialEntity = (
  data: Record<string, unknown>,
  schema: Schema
): ValidationResult => {
  const errors: ValidationError[] = [];

  // Only validate fields that are present in the data
  for (const [columnName, value] of Object.entries(data)) {
    const columnDef = schema.columns[columnName];

    if (!columnDef) {
      errors.push({
        field: columnName,
        message: `Unexpected field '${columnName}' not defined in schema '${schema.name}'`,
        value,
      });
      continue;
    }

    // For partial validation, ignore the 'required' constraint
    const result = validateColumn(value, { ...columnDef, required: false }, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

Version 2

'use strict';

import { Schema, SchemaColumn } from '../types';

export type ValidationError = {
  field: string;
  message: string;
  value?: unknown;
};

export type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];
};

/**
 * Validate a single column value against its schema definition
 */
export const validateColumn = (
  value: unknown,
  column: SchemaColumn,
  fieldName?: string
): ValidationResult => {
  const errors: ValidationError[] = [];
  const field = fieldName || column.name;

  // Check required
  if (column.required && (value === null || value === undefined)) {
    errors.push({
      field,
      message: `Field '${field}' is required`,
      value,
    });
    return { valid: false, errors };
  }

  // If value is null/undefined and not required, skip further validation
  if (value === null || value === undefined) {
    return { valid: true, errors: [] };
  }

  // Type validation
  const actualType = typeof value;
  let expectedType = column.type;
  if (expectedType === 'object') expectedType = 'object';

  if (actualType !== expectedType) {
    errors.push({
      field,
      message: `Field '${field}' must be of type ${column.type}, got ${actualType}`,
      value,
    });
    return { valid: false, errors };
  }

  // String validation
  if (column.type === 'string' && typeof value === 'string') {
    if (column.minLength !== undefined && value.length < column.minLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.maxLength !== undefined && value.length > column.maxLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.regex && !column.regex.test(value)) {
      errors.push({
        field,
        message: `Field '${field}' does not match required format`,
        value,
      });
    }

    if (column.values && !column.values.includes(value)) {
      errors.push({
        field,
        message: `Field '${field}' must be one of: [${column.values.join(', ')}], got '${value}'`,
        value,
      });
    }
  }

  // Number validation
  if (column.type === 'number' && typeof value === 'number') {
    if (column.minValue !== undefined && value < column.minValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minValue}, got ${value}`,
        value,
      });
    }

    if (column.maxValue !== undefined && value > column.maxValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxValue}, got ${value}`,
        value,
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate an entire entity against its schema
 */
export const validateEntity = (data: Record<string, unknown>, schema: Schema): ValidationResult => {
  const errors: ValidationError[] = [];

  // Validate each column in the schema
  for (const [columnName, columnDef] of Object.entries(schema.columns)) {
    const value = data[columnName];
    const result = validateColumn(value, columnDef, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  // Check for unexpected fields
  for (const key of Object.keys(data)) {
    if (!schema.columns[key]) {
      errors.push({
        field: key,
        message: `Unexpected field '${key}' not defined in schema '${schema.name}'`,
        value: data[key],
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate a partial entity (useful for updates where not all fields are provided)
 */
export const validatePartialEntity = (
  data: Record<string, unknown>,
  schema: Schema
): ValidationResult => {
  const errors: ValidationError[] = [];

  // Only validate fields that are present in the data
  for (const [columnName, value] of Object.entries(data)) {
    const columnDef = schema.columns[columnName];

    if (!columnDef) {
      errors.push({
        field: columnName,
        message: `Unexpected field '${columnName}' not defined in schema '${schema.name}'`,
        value,
      });
      continue;
    }

    // For partial validation, ignore the 'required' constraint
    const result = validateColumn(value, { ...columnDef, required: false }, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

Version 3

'use strict';

import { ZodError } from 'zod';
import { Schema, SchemaColumn } from '../types';

export type ValidationError = {
  field: string;
  message: string;
  value?: unknown;
};

export type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];
};

/**
 * Validate a single column value against its schema definition
 */
export const validateColumn = (
  value: unknown,
  column: SchemaColumn,
  fieldName?: string
): ValidationResult => {
  const errors: ValidationError[] = [];
  const field = fieldName || column.name;

  // Use Zod validation if zodValidator is present
  if (column.zodValidator) {
    try {
      column.zodValidator.parse(value);
      return { valid: true, errors: [] };
    } catch (error) {
      if (error instanceof ZodError) {
        // Convert Zod errors to our ValidationError format
        const zodErrors = error.errors.map((err) => ({
          field,
          message: err.message,
          value,
        }));
        return { valid: false, errors: zodErrors };
      }
      // Re-throw unexpected errors
      throw error;
    }
  }

  // Fall back to custom validation when no zodValidator

  // Check required
  if (column.required && (value === null || value === undefined)) {
    errors.push({
      field,
      message: `Field '${field}' is required`,
      value,
    });
    return { valid: false, errors };
  }

  // If value is null/undefined and not required, skip further validation
  if (value === null || value === undefined) {
    return { valid: true, errors: [] };
  }

  // Type validation
  const actualType = typeof value;
  let expectedType = column.type;
  if (expectedType === 'object') expectedType = 'object';

  if (actualType !== expectedType) {
    errors.push({
      field,
      message: `Field '${field}' must be of type ${column.type}, got ${actualType}`,
      value,
    });
    return { valid: false, errors };
  }

  // String validation
  if (column.type === 'string' && typeof value === 'string') {
    if (column.minLength !== undefined && value.length < column.minLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.maxLength !== undefined && value.length > column.maxLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.regex && !column.regex.test(value)) {
      errors.push({
        field,
        message: `Field '${field}' does not match required format`,
        value,
      });
    }

    if (column.values && !column.values.includes(value)) {
      errors.push({
        field,
        message: `Field '${field}' must be one of: [${column.values.join(', ')}], got '${value}'`,
        value,
      });
    }
  }

  // Number validation
  if (column.type === 'number' && typeof value === 'number') {
    if (column.minValue !== undefined && value < column.minValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minValue}, got ${value}`,
        value,
      });
    }

    if (column.maxValue !== undefined && value > column.maxValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxValue}, got ${value}`,
        value,
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate an entire entity against its schema
 */
export const validateEntity = (data: Record<string, unknown>, schema: Schema): ValidationResult => {
  const errors: ValidationError[] = [];

  // Validate each column in the schema
  for (const [columnName, columnDef] of Object.entries(schema.columns)) {
    const value = data[columnName];
    const result = validateColumn(value, columnDef, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  // Check for unexpected fields
  for (const key of Object.keys(data)) {
    if (!schema.columns[key]) {
      errors.push({
        field: key,
        message: `Unexpected field '${key}' not defined in schema '${schema.name}'`,
        value: data[key],
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate a partial entity (useful for updates where not all fields are provided)
 */
export const validatePartialEntity = (
  data: Record<string, unknown>,
  schema: Schema
): ValidationResult => {
  const errors: ValidationError[] = [];

  // Only validate fields that are present in the data
  for (const [columnName, value] of Object.entries(data)) {
    const columnDef = schema.columns[columnName];

    if (!columnDef) {
      errors.push({
        field: columnName,
        message: `Unexpected field '${columnName}' not defined in schema '${schema.name}'`,
        value,
      });
      continue;
    }

    // For partial validation, ignore the 'required' constraint
    const result = validateColumn(value, { ...columnDef, required: false }, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

Version 4 (latest)

'use strict';

import { ZodError } from 'zod';
import { Schema, SchemaColumn } from '../types';

export type ValidationError = {
  field: string;
  message: string;
  value?: unknown;
};

export type ValidationResult = {
  valid: boolean;
  errors: ValidationError[];
};

/**
 * Validate a single column value against its schema definition
 */
export const validateColumn = (
  value: unknown,
  column: SchemaColumn,
  fieldName?: string
): ValidationResult => {
  const errors: ValidationError[] = [];
  const field = fieldName || column.name;

  // Use Zod validation if zodValidator is present
  if (column.zodValidator) {
    try {
      column.zodValidator.parse(value);
      return { valid: true, errors: [] };
    } catch (error) {
      if (error instanceof ZodError) {
        // Convert Zod errors to our ValidationError format
        const zodErrors = error.errors.map((err) => ({
          field,
          message: err.message,
          value,
        }));
        return { valid: false, errors: zodErrors };
      }
      // Re-throw unexpected errors
      throw error;
    }
  }

  // Fall back to custom validation when no zodValidator

  // Check required
  if (column.required && (value === null || value === undefined)) {
    errors.push({
      field,
      message: `Field '${field}' is required`,
      value,
    });
    return { valid: false, errors };
  }

  // If value is null/undefined and not required, skip further validation
  if (value === null || value === undefined) {
    return { valid: true, errors: [] };
  }

  // Type validation
  const actualType = typeof value;
  let expectedType = column.type;
  if (expectedType === 'object') expectedType = 'object';

  if (actualType !== expectedType) {
    errors.push({
      field,
      message: `Field '${field}' must be of type ${column.type}, got ${actualType}`,
      value,
    });
    return { valid: false, errors };
  }

  // String validation
  if (column.type === 'string' && typeof value === 'string') {
    if (column.minLength !== undefined && value.length < column.minLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.maxLength !== undefined && value.length > column.maxLength) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxLength} characters, got ${value.length}`,
        value,
      });
    }

    if (column.regex && !column.regex.test(value)) {
      errors.push({
        field,
        message: `Field '${field}' does not match required format`,
        value,
      });
    }

    if (column.values && !column.values.includes(value)) {
      errors.push({
        field,
        message: `Field '${field}' must be one of: [${column.values.join(', ')}], got '${value}'`,
        value,
      });
    }
  }

  // Number validation
  if (column.type === 'number' && typeof value === 'number') {
    if (column.minValue !== undefined && value < column.minValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at least ${column.minValue}, got ${value}`,
        value,
      });
    }

    if (column.maxValue !== undefined && value > column.maxValue) {
      errors.push({
        field,
        message: `Field '${field}' must be at most ${column.maxValue}, got ${value}`,
        value,
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate an entire entity against its schema
 */
export const validateEntity = (data: Record<string, unknown>, schema: Schema): ValidationResult => {
  const errors: ValidationError[] = [];

  // Validate each column in the schema
  for (const [columnName, columnDef] of Object.entries(schema.columns)) {
    const value = data[columnName];
    const result = validateColumn(value, columnDef, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  // Check for unexpected fields
  for (const key of Object.keys(data)) {
    if (!schema.columns[key]) {
      errors.push({
        field: key,
        message: `Unexpected field '${key}' not defined in schema '${schema.name}'`,
        value: data[key],
      });
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

/**
 * Validate a partial entity (useful for updates where not all fields are provided)
 */
export const validatePartialEntity = (
  data: Record<string, unknown>,
  schema: Schema
): ValidationResult => {
  const errors: ValidationError[] = [];

  // Only validate fields that are present in the data
  for (const [columnName, value] of Object.entries(data)) {
    const columnDef = schema.columns[columnName];

    if (!columnDef) {
      errors.push({
        field: columnName,
        message: `Unexpected field '${columnName}' not defined in schema '${schema.name}'`,
        value,
      });
      continue;
    }

    // For partial validation, ignore the 'required' constraint
    const result = validateColumn(value, { ...columnDef, required: false }, columnName);

    if (!result.valid) {
      errors.push(...result.errors);
    }
  }

  return {
    valid: errors.length === 0,
    errors,
  };
};

packages/cwc-schema/src/validation/zodValidators.ts

3 versions

Version 1

'use strict';

import { z } from 'zod';

/**
 * Example Zod validators for complex validation scenarios.
 *
 * Use Zod validators when:
 * - Password strength requirements (uppercase, lowercase, numbers, special chars)
 * - Conditional validation (different rules based on other fields)
 * - Cross-field validation (one field depends on another)
 * - Complex business logic (custom refinements)
 * - Advanced string parsing (dates, URLs, transforms)
 *
 * Use custom validation when:
 * - Simple min/max length checks
 * - Simple regex patterns
 * - Basic enum values
 * - Basic type checking
 */

/**
 * Password strength validator
 *
 * Requirements:
 * - At least 8 characters
 * - At least one uppercase letter
 * - At least one lowercase letter
 * - At least one number
 * - At least one special character
 *
 * Usage:
 * ```typescript
 * password: {
 *   ...password,
 *   zodValidator: passwordStrengthValidator,
 * }
 * ```
 */
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

/**
 * Email validator with stricter rules than basic regex
 *
 * Requirements:
 * - Valid email format
 * - No consecutive dots
 * - No leading/trailing dots in local part
 * - Domain must have at least 2 parts
 *
 * Usage:
 * ```typescript
 * email: {
 *   ...email,
 *   zodValidator: strictEmailValidator,
 * }
 * ```
 */
export const strictEmailValidator = z
  .string()
  .email('Invalid email format')
  .refine((val) => !val.includes('..'), {
    message: 'Email cannot contain consecutive dots',
  })
  .refine((val) => {
    const [localPart] = val.split('@');
    if (!localPart) return false;
    return !localPart.startsWith('.') && !localPart.endsWith('.');
  }, {
    message: 'Email local part cannot start or end with a dot',
  });

/**
 * Username validator with profanity check
 *
 * Requirements:
 * - 4-100 alphanumeric characters or underscores
 * - No profanity (example blacklist)
 *
 * Usage:
 * ```typescript
 * username: {
 *   ...username,
 *   zodValidator: usernameWithProfanityCheck,
 * }
 * ```
 */
const profanityBlacklist = ['badword1', 'badword2', 'admin', 'root', 'system'];

export const usernameWithProfanityCheck = z
  .string()
  .min(4, 'Username must be at least 4 characters')
  .max(100, 'Username must be at most 100 characters')
  .regex(/^[a-zA-Z0-9_]+$/, 'Username can only contain letters, numbers, and underscores')
  .refine((val) => !profanityBlacklist.some((word) => val.toLowerCase().includes(word)), {
    message: 'Username contains prohibited words',
  });

/**
 * URL validator with allowed domains
 *
 * Requirements:
 * - Valid URL format
 * - HTTPS only
 * - Must be from allowed domains
 *
 * Usage:
 * ```typescript
 * websiteUrl: {
 *   type: 'string',
 *   name: 'websiteUrl',
 *   typename: 'url',
 *   zodValidator: allowedDomainsUrlValidator(['example.com', 'mysite.com']),
 * }
 * ```
 */
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        // Extract hostname from URL string (simpler than URL constructor)
        const match = val.match(/^https?:\/\/([^/:]+)/);
        if (!match || !match[1]) return false;
        const hostname = match[1];
        return allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

/**
 * Conditional validator example: different rules based on login type
 *
 * This shows how to create validators that change behavior based on context.
 * Note: For cross-field validation, you'd typically validate at the entity level,
 * not the column level. This is a simplified example.
 *
 * Usage:
 * ```typescript
 * // In a custom validation function at entity level:
 * const loginType = data.loginType as string;
 * const passwordValidator = loginType === 'cwc' ? passwordRequiredValidator : passwordOptionalValidator;
 * ```
 */
export const passwordRequiredValidator = z
  .string()
  .min(1, 'Password is required for CWC login');

export const passwordOptionalValidator = z
  .string()
  .optional()
  .nullable();

/**
 * Date range validator
 *
 * Ensures date is within acceptable range (e.g., not in future, not too old)
 *
 * Usage:
 * ```typescript
 * birthDate: {
 *   type: 'string',
 *   name: 'birthDate',
 *   typename: 'date',
 *   zodValidator: dateRangeValidator({ minYearsAgo: 100, maxYearsAgo: 13 }),
 * }
 * ```
 */
export const dateRangeValidator = (options: { minYearsAgo?: number; maxYearsAgo?: number }) =>
  z.string().refine(
    (val) => {
      const date = new Date(val);
      if (isNaN(date.getTime())) return false;

      const now = new Date();
      const minDate = options.minYearsAgo
        ? new Date(now.getFullYear() - options.minYearsAgo, now.getMonth(), now.getDate())
        : new Date(0);
      const maxDate = options.maxYearsAgo
        ? new Date(now.getFullYear() - options.maxYearsAgo, now.getMonth(), now.getDate())
        : now;

      return date >= minDate && date <= maxDate;
    },
    {
      message: `Date must be between ${options.minYearsAgo || 0} and ${options.maxYearsAgo || 0} years ago`,
    }
  );

/**
 * JSON string validator with schema
 *
 * Validates that a string is valid JSON and matches a specific structure
 *
 * Usage:
 * ```typescript
 * metadata: {
 *   type: 'string',
 *   name: 'metadata',
 *   typename: 'json',
 *   zodValidator: jsonStringValidator(z.object({
 *     version: z.string(),
 *     timestamp: z.number(),
 *   })),
 * }
 * ```
 */
export const jsonStringValidator = <T extends z.ZodType>(schema: T) =>
  z.string().transform((val, ctx) => {
    try {
      const parsed = JSON.parse(val);
      const result = schema.safeParse(parsed);
      if (!result.success) {
        result.error.errors.forEach((err) => {
          ctx.addIssue({
            code: z.ZodIssueCode.custom,
            message: `Invalid JSON structure: ${err.message}`,
          });
        });
        return z.NEVER;
      }
      return parsed;
    } catch {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Invalid JSON string',
      });
      return z.NEVER;
    }
  });

Version 2

'use strict';

import { z } from 'zod';

/**
 * Example Zod validators for complex validation scenarios.
 *
 * Use Zod validators when:
 * - Password strength requirements (uppercase, lowercase, numbers, special chars)
 * - Conditional validation (different rules based on other fields)
 * - Cross-field validation (one field depends on another)
 * - Complex business logic (custom refinements)
 * - Advanced string parsing (dates, URLs, transforms)
 *
 * Use custom validation when:
 * - Simple min/max length checks
 * - Simple regex patterns
 * - Basic enum values
 * - Basic type checking
 */

/**
 * Password strength validator
 *
 * Requirements:
 * - At least 8 characters
 * - At least one uppercase letter
 * - At least one lowercase letter
 * - At least one number
 * - At least one special character
 *
 * Usage:
 * ```typescript
 * password: {
 *   ...password,
 *   zodValidator: passwordStrengthValidator,
 * }
 * ```
 */
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

/**
 * Email validator with stricter rules than basic regex
 *
 * Requirements:
 * - Valid email format
 * - No consecutive dots
 * - No leading/trailing dots in local part
 * - Domain must have at least 2 parts
 *
 * Usage:
 * ```typescript
 * email: {
 *   ...email,
 *   zodValidator: strictEmailValidator,
 * }
 * ```
 */
export const strictEmailValidator = z
  .string()
  .email('Invalid email format')
  .refine((val) => !val.includes('..'), {
    message: 'Email cannot contain consecutive dots',
  })
  .refine((val) => {
    const [localPart] = val.split('@');
    if (!localPart) return false;
    return !localPart.startsWith('.') && !localPart.endsWith('.');
  }, {
    message: 'Email local part cannot start or end with a dot',
  });

/**
 * Username validator with profanity check
 *
 * Requirements:
 * - 4-100 alphanumeric characters or underscores
 * - No profanity (example blacklist)
 *
 * Usage:
 * ```typescript
 * username: {
 *   ...username,
 *   zodValidator: usernameWithProfanityCheck,
 * }
 * ```
 */
const profanityBlacklist = ['badword1', 'badword2', 'admin', 'root', 'system'];

export const usernameWithProfanityCheck = z
  .string()
  .min(4, 'Username must be at least 4 characters')
  .max(100, 'Username must be at most 100 characters')
  .regex(/^[a-zA-Z0-9_]+$/, 'Username can only contain letters, numbers, and underscores')
  .refine((val) => !profanityBlacklist.some((word) => val.toLowerCase().includes(word)), {
    message: 'Username contains prohibited words',
  });

/**
 * URL validator with allowed domains
 *
 * Requirements:
 * - Valid URL format
 * - HTTPS only
 * - Must be from allowed domains
 *
 * Usage:
 * ```typescript
 * websiteUrl: {
 *   type: 'string',
 *   name: 'websiteUrl',
 *   typename: 'url',
 *   zodValidator: allowedDomainsUrlValidator(['example.com', 'mysite.com']),
 * }
 * ```
 */
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        // Extract hostname from URL string (simpler than URL constructor)
        const match = val.match(/^https?:\/\/([^/:]+)/);
        if (!match || !match[1]) return false;
        const hostname = match[1];
        return allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

/**
 * Conditional validator example: different rules based on login type
 *
 * This shows how to create validators that change behavior based on context.
 * Note: For cross-field validation, you'd typically validate at the entity level,
 * not the column level. This is a simplified example.
 *
 * Usage:
 * ```typescript
 * // In a custom validation function at entity level:
 * const loginType = data.loginType as string;
 * const passwordValidator = loginType === 'cwc' ? passwordRequiredValidator : passwordOptionalValidator;
 * ```
 */
export const passwordRequiredValidator = z
  .string()
  .min(1, 'Password is required for CWC login');

export const passwordOptionalValidator = z
  .string()
  .optional()
  .nullable();

/**
 * Date range validator
 *
 * Ensures date is within acceptable range (e.g., not in future, not too old)
 *
 * Usage:
 * ```typescript
 * birthDate: {
 *   type: 'string',
 *   name: 'birthDate',
 *   typename: 'date',
 *   zodValidator: dateRangeValidator({ minYearsAgo: 100, maxYearsAgo: 13 }),
 * }
 * ```
 */
export const dateRangeValidator = (options: { minYearsAgo?: number; maxYearsAgo?: number }) =>
  z.string().refine(
    (val) => {
      const date = new Date(val);
      if (isNaN(date.getTime())) return false;

      const now = new Date();
      const minDate = options.minYearsAgo
        ? new Date(now.getFullYear() - options.minYearsAgo, now.getMonth(), now.getDate())
        : new Date(0);
      const maxDate = options.maxYearsAgo
        ? new Date(now.getFullYear() - options.maxYearsAgo, now.getMonth(), now.getDate())
        : now;

      return date >= minDate && date <= maxDate;
    },
    {
      message: `Date must be between ${options.minYearsAgo || 0} and ${options.maxYearsAgo || 0} years ago`,
    }
  );

/**
 * JSON string validator with schema
 *
 * Validates that a string is valid JSON and matches a specific structure
 *
 * Usage:
 * ```typescript
 * metadata: {
 *   type: 'string',
 *   name: 'metadata',
 *   typename: 'json',
 *   zodValidator: jsonStringValidator(z.object({
 *     version: z.string(),
 *     timestamp: z.number(),
 *   })),
 * }
 * ```
 */
export const jsonStringValidator = <T extends z.ZodType>(schema: T) =>
  z.string().transform((val, ctx) => {
    try {
      const parsed = JSON.parse(val);
      const result = schema.safeParse(parsed);
      if (!result.success) {
        result.error.errors.forEach((err) => {
          ctx.addIssue({
            code: z.ZodIssueCode.custom,
            message: `Invalid JSON structure: ${err.message}`,
          });
        });
        return z.NEVER;
      }
      return parsed;
    } catch {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Invalid JSON string',
      });
      return z.NEVER;
    }
  });

Version 3 (latest)

'use strict';

import { z } from 'zod';

/**
 * Example Zod validators for complex validation scenarios.
 *
 * Use Zod validators when:
 * - Password strength requirements (uppercase, lowercase, numbers, special chars)
 * - Conditional validation (different rules based on other fields)
 * - Cross-field validation (one field depends on another)
 * - Complex business logic (custom refinements)
 * - Advanced string parsing (dates, URLs, transforms)
 *
 * Use custom validation when:
 * - Simple min/max length checks
 * - Simple regex patterns
 * - Basic enum values
 * - Basic type checking
 */

/**
 * Password strength validator
 *
 * Requirements:
 * - At least 8 characters
 * - At least one uppercase letter
 * - At least one lowercase letter
 * - At least one number
 * - At least one special character
 *
 * Usage:
 * ```typescript
 * password: {
 *   ...password,
 *   zodValidator: passwordStrengthValidator,
 * }
 * ```
 */
export const passwordStrengthValidator = z
  .string()
  .min(8, 'Password must be at least 8 characters')
  .max(100, 'Password must be at most 100 characters')
  .refine((val) => /[A-Z]/.test(val), {
    message: 'Password must contain at least one uppercase letter',
  })
  .refine((val) => /[a-z]/.test(val), {
    message: 'Password must contain at least one lowercase letter',
  })
  .refine((val) => /[0-9]/.test(val), {
    message: 'Password must contain at least one number',
  })
  .refine((val) => /[^A-Za-z0-9]/.test(val), {
    message: 'Password must contain at least one special character',
  });

/**
 * Email validator with stricter rules than basic regex
 *
 * Requirements:
 * - Valid email format
 * - No consecutive dots
 * - No leading/trailing dots in local part
 * - Domain must have at least 2 parts
 *
 * Usage:
 * ```typescript
 * email: {
 *   ...email,
 *   zodValidator: strictEmailValidator,
 * }
 * ```
 */
export const strictEmailValidator = z
  .string()
  .email('Invalid email format')
  .refine((val) => !val.includes('..'), {
    message: 'Email cannot contain consecutive dots',
  })
  .refine((val) => {
    const [localPart] = val.split('@');
    if (!localPart) return false;
    return !localPart.startsWith('.') && !localPart.endsWith('.');
  }, {
    message: 'Email local part cannot start or end with a dot',
  });

/**
 * URL validator with allowed domains
 *
 * Requirements:
 * - Valid URL format
 * - HTTPS only
 * - Must be from allowed domains
 *
 * Usage:
 * ```typescript
 * websiteUrl: {
 *   type: 'string',
 *   name: 'websiteUrl',
 *   typename: 'url',
 *   zodValidator: allowedDomainsUrlValidator(['example.com', 'mysite.com']),
 * }
 * ```
 */
export const allowedDomainsUrlValidator = (allowedDomains: string[]) =>
  z
    .string()
    .url('Invalid URL format')
    .refine((val) => val.startsWith('https://'), {
      message: 'URL must use HTTPS',
    })
    .refine(
      (val) => {
        // Extract hostname from URL string (simpler than URL constructor)
        const match = val.match(/^https?:\/\/([^/:]+)/);
        if (!match || !match[1]) return false;
        const hostname = match[1];
        return allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
      },
      {
        message: `URL must be from allowed domains: ${allowedDomains.join(', ')}`,
      }
    );

/**
 * Conditional validator example: different rules based on login type
 *
 * This shows how to create validators that change behavior based on context.
 * Note: For cross-field validation, you'd typically validate at the entity level,
 * not the column level. This is a simplified example.
 *
 * Usage:
 * ```typescript
 * // In a custom validation function at entity level:
 * const loginType = data.loginType as string;
 * const passwordValidator = loginType === 'cwc' ? passwordRequiredValidator : passwordOptionalValidator;
 * ```
 */
export const passwordRequiredValidator = z
  .string()
  .min(1, 'Password is required for CWC login');

export const passwordOptionalValidator = z
  .string()
  .optional()
  .nullable();

/**
 * Date range validator
 *
 * Ensures date is within acceptable range (e.g., not in future, not too old)
 *
 * Usage:
 * ```typescript
 * birthDate: {
 *   type: 'string',
 *   name: 'birthDate',
 *   typename: 'date',
 *   zodValidator: dateRangeValidator({ minYearsAgo: 100, maxYearsAgo: 13 }),
 * }
 * ```
 */
export const dateRangeValidator = (options: { minYearsAgo?: number; maxYearsAgo?: number }) =>
  z.string().refine(
    (val) => {
      const date = new Date(val);
      if (isNaN(date.getTime())) return false;

      const now = new Date();
      const minDate = options.minYearsAgo
        ? new Date(now.getFullYear() - options.minYearsAgo, now.getMonth(), now.getDate())
        : new Date(0);
      const maxDate = options.maxYearsAgo
        ? new Date(now.getFullYear() - options.maxYearsAgo, now.getMonth(), now.getDate())
        : now;

      return date >= minDate && date <= maxDate;
    },
    {
      message: `Date must be between ${options.minYearsAgo || 0} and ${options.maxYearsAgo || 0} years ago`,
    }
  );

/**
 * JSON string validator with schema
 *
 * Validates that a string is valid JSON and matches a specific structure
 *
 * Usage:
 * ```typescript
 * metadata: {
 *   type: 'string',
 *   name: 'metadata',
 *   typename: 'json',
 *   zodValidator: jsonStringValidator(z.object({
 *     version: z.string(),
 *     timestamp: z.number(),
 *   })),
 * }
 * ```
 */
export const jsonStringValidator = <T extends z.ZodType>(schema: T) =>
  z.string().transform((val, ctx) => {
    try {
      const parsed = JSON.parse(val);
      const result = schema.safeParse(parsed);
      if (!result.success) {
        result.error.errors.forEach((err) => {
          ctx.addIssue({
            code: z.ZodIssueCode.custom,
            message: `Invalid JSON structure: ${err.message}`,
          });
        });
        return z.NEVER;
      }
      return parsed;
    } catch {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: 'Invalid JSON string',
      });
      return z.NEVER;
    }
  });

packages/cwc-schema/tsconfig.json

2 versions

Version 1

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Version 2 (latest)

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

tsconfig.base.json

2 versions

Version 1

{
  "compilerOptions": {
    /* Language and Environment */
    "target": "ES2022",
    "lib": ["ES2022"],

    /* Modules */
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "resolveJsonModule": true,

    /* Emit */
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "removeComments": true,
    "incremental": true,

    /* Interop Constraints */
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,

    /* Type Checking - STRICT MODE */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,

    /* Completeness */
    "skipLibCheck": true,

    /* Disallow JavaScript */
    "allowJs": false,
    "checkJs": false
  },
  "exclude": ["node_modules", "dist", "coverage", ".turbo"]
}

Version 2 (latest)

{
  "compilerOptions": {
    /* Language and Environment */
    "target": "ES2022",
    "lib": ["ES2022"],

    /* Modules */
    "module": "ES2022",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,

    /* Emit */
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "removeComments": true,
    "incremental": true,

    /* Interop Constraints */
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,

    /* Type Checking - STRICT MODE */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,

    /* Completeness */
    "skipLibCheck": true,

    /* Disallow JavaScript */
    "allowJs": false,
    "checkJs": false
  },
  "exclude": ["node_modules", "dist", "coverage", ".turbo"]
}

Session 07: cwc shema

Session 07: cwc shema

Schema-Driven Database Architecture for CWC

Preface

Overview

Architecture Pattern

Three-Tier Approach

Core Benefits

Implementation Guide

File Structure

Step 1: Define Types (types.ts)

Step 2: Extract Regex Patterns (validation/regexPatterns.ts)

Step 3: Define Reusable Column Types (columnTypes.ts)

Step 4: Define Table Schemas (tables/user.ts)

Step 5: Aggregate Schemas (index.ts)

Critical Patterns

1. Never Hardcode Database Structure

2. Use Spread Syntax for Customization

3. Maintain Alphabetical Order

4. One File Per Table/View

5. Semantic Type Names

Example Usage

In Services

In Tests

Summary of Steps

Current Setup: NodeNext

Better Alternative for TypeScript Libraries: "Bundler"

Comparison Table

Recommendation

My Opinion

✅ cwc-schema Package Complete

What was built:

Key Features:

Honest Assessment: Custom Schema vs Zod

What We Built (Custom)

What Zod Would Provide

My Honest Take

Suggested Improvements (If Staying Custom)

1. Add Type Inference

2. Add Schema Composition

3. Better Error Messages

4. Add Transforms

Memory File Updates

The 4 Improvements I Mentioned:

1. Add Type Inference

2. Add Schema Composition

3. Better Error Messages

4. Add Transforms

What We Should Do Now

What Was Added

Honest Assessment of cwc-schema

What We Successfully Implemented

Critical Limitations vs Zod

Side-by-Side: Real Example

Our Implementation

Zod Implementation

The Real Problem: Duplication

My Honest Recommendation

Option 1: Switch to Zod (Recommended)

Option 2: Enhance Custom Implementation

Option 3: Hybrid Approach

My Verdict

Major Schema Validation Libraries

1. Zod (Most Popular, TypeScript-First)

2. Yup (Most Established, Pre-TypeScript Era)

3. Valibot (Smallest, Zod-Inspired)

4. ArkType (Fastest, String-Based Syntax)

5. TypeBox (JSON Schema Native)

6. io-ts (Functional Programming Style)

7. Joi (Backend-Focused, Hapi Ecosystem)

8. Superstruct (Minimalist)

Comparison Table

My Recommendations by Use Case

For Your Project (cwc-schema)

My Specific Recommendation

Why Zod Gives You MORE Control Than Yup/Joi

Hybrid Approach: Best of Both Worlds

Pattern 1: Custom Schema + Zod Validators (Recommended)

Pattern 2: Custom Schema, Convert to Zod On-Demand

Pattern 3: Zod for Complex, Custom for Simple

Step 1: Define Types (`types.ts`)

Step 2: Extract Regex Patterns (`validation/regexPatterns.ts`)

Step 3: Define Reusable Column Types (`columnTypes.ts`)

Step 4: Define Table Schemas (`tables/user.ts`)

Step 5: Aggregate Schemas (`index.ts`)

2. Update type definitions (`src/types.ts`)

3. Update validation logic (`src/validation/validator.ts`)

4. Create example Zod validators (`src/validation/zodValidators.ts`)

5. Update documentation (`CLAUDE.md`)

2. Updated Type Definitions (`src/types.ts`)

3. Enhanced Validation Logic (`src/validation/validator.ts`)

4. Created Example Validators (`src/validation/zodValidators.ts`)

6. Comprehensive Documentation (`CLAUDE.md`)