@parsrun/entity 0.1.35

package/src/define.ts

@@ -0,0 +1,313 @@
+import { type, type Type } from 'arktype'
+import type {
+  EntityDefinition,
+  Field,
+  FieldDefinition,
+  Entity,
+} from './types.js'
+
+/**
+ * Convert a field definition to an ArkType type string
+ */
+function fieldToArkType(field: Field): string {
+  const def: FieldDefinition = typeof field === 'string'
+    ? { type: field }
+    : field
+
+  let typeStr = def.type
+
+  // Handle min/max constraints
+  if (def.min !== undefined || def.max !== undefined) {
+    if (typeStr === 'string' || typeStr.startsWith('string')) {
+      if (def.min !== undefined && def.max !== undefined) {
+        typeStr = `string >= ${def.min} <= ${def.max}`
+      } else if (def.min !== undefined) {
+        typeStr = `string >= ${def.min}`
+      } else if (def.max !== undefined) {
+        typeStr = `string <= ${def.max}`
+      }
+    } else if (typeStr === 'number' || typeStr.startsWith('number')) {
+      const base = typeStr.includes('.integer') ? 'number.integer' : 'number'
+      if (def.min !== undefined && def.max !== undefined) {
+        typeStr = `${base} >= ${def.min} <= ${def.max}`
+      } else if (def.min !== undefined) {
+        typeStr = `${base} >= ${def.min}`
+      } else if (def.max !== undefined) {
+        typeStr = `${base} <= ${def.max}`
+      }
+    }
+  }
+
+  // Handle optional fields
+  if (def.optional) {
+    // For optional fields, allow undefined or the type
+    typeStr = `${typeStr} | undefined`
+  }
+
+  return typeStr
+}
+
+/**
+ * Build the full schema object for ArkType
+ */
+function buildSchemaObject(
+  definition: EntityDefinition<Record<string, Field>>,
+  mode: 'full' | 'create' | 'update' | 'query'
+): Record<string, string> {
+  const schema: Record<string, string> = {}
+
+  // Add id field for full schema
+  if (mode === 'full') {
+    schema['id'] = 'string.uuid'
+  }
+
+  // Add tenantId if tenant-scoped
+  if (definition.tenant) {
+    if (mode === 'full' || mode === 'create') {
+      schema['tenantId'] = 'string.uuid'
+    }
+    if (mode === 'query') {
+      schema['tenantId?'] = 'string.uuid'
+    }
+  }
+
+  // Add user-defined fields
+  for (const [name, field] of Object.entries(definition.fields)) {
+    const def: FieldDefinition = typeof field === 'string'
+      ? { type: field }
+      : field
+
+    if (mode === 'update' || mode === 'query') {
+      // All fields optional for update/query
+      schema[`${name}?`] = fieldToArkType(field)
+    } else if (mode === 'create') {
+      // Skip fields with defaults or optional fields
+      if (def.default !== undefined || def.optional) {
+        schema[`${name}?`] = fieldToArkType(field)
+      } else {
+        schema[name] = fieldToArkType(field)
+      }
+    } else {
+      // Full schema
+      if (def.optional) {
+        schema[`${name}?`] = fieldToArkType(field)
+      } else {
+        schema[name] = fieldToArkType(field)
+      }
+    }
+  }
+
+  // Add timestamp fields
+  if (definition.timestamps) {
+    if (mode === 'full') {
+      schema['insertedAt'] = 'Date'
+      schema['updatedAt'] = 'Date'
+    }
+    if (mode === 'query') {
+      schema['insertedAt?'] = 'Date'
+      schema['updatedAt?'] = 'Date'
+      schema['insertedAfter?'] = 'Date'
+      schema['insertedBefore?'] = 'Date'
+    }
+  }
+
+  // Add soft delete field
+  if (definition.softDelete) {
+    if (mode === 'full') {
+      schema['deletedAt?'] = 'Date'
+    }
+    if (mode === 'query') {
+      schema['includeDeleted?'] = 'boolean'
+    }
+  }
+
+  // Add pagination for query
+  if (mode === 'query') {
+    schema['limit?'] = 'number.integer > 0'
+    schema['offset?'] = 'number.integer >= 0'
+    schema['cursor?'] = 'string'
+    schema['orderBy?'] = 'string'
+    schema['orderDirection?'] = "'asc' | 'desc'"
+    schema['search?'] = 'string'
+  }
+
+  return schema
+}
+
+/**
+ * Define an entity with single-source schema generation
+ *
+ * @example
+ * ```typescript
+ * const Product = defineEntity({
+ *   name: 'products',
+ *   tenant: true,
+ *   timestamps: true,
+ *   softDelete: true,
+ *   fields: {
+ *     name: 'string >= 1',
+ *     price: { type: 'number', min: 0 },
+ *     status: "'draft' | 'active' | 'archived'",
+ *   },
+ *   indexes: [
+ *     { fields: ['tenantId', 'status'] },
+ *   ],
+ * })
+ *
+ * // Use schemas
+ * const validated = Product.createSchema(input)
+ * const products = await db.select().from(Product.table)
+ * ```
+ */
+export function defineEntity<
+  TName extends string,
+  TFields extends Record<string, Field>,
+>(
+  definition: EntityDefinition<TFields> & { name: TName }
+): Entity<TName, TFields, Record<string, unknown>> {
+  // Build schema objects
+  const fullSchemaObj = buildSchemaObject(definition, 'full')
+  const createSchemaObj = buildSchemaObject(definition, 'create')
+  const updateSchemaObj = buildSchemaObject(definition, 'update')
+  const querySchemaObj = buildSchemaObject(definition, 'query')
+
+  // Create ArkType schemas
+  const schema = type(fullSchemaObj as Record<string, string>)
+  const createSchema = type(createSchemaObj as Record<string, string>)
+  const updateSchema = type(updateSchemaObj as Record<string, string>)
+  const querySchema = type(querySchemaObj as Record<string, string>)
+
+  // Determine auto and required fields
+  const autoFields: string[] = ['id']
+  if (definition.timestamps) {
+    autoFields.push('insertedAt', 'updatedAt')
+  }
+  if (definition.softDelete) {
+    autoFields.push('deletedAt')
+  }
+
+  const requiredFields: string[] = []
+  const optionalFields: string[] = []
+
+  if (definition.tenant) {
+    requiredFields.push('tenantId')
+  }
+
+  for (const [name, field] of Object.entries(definition.fields)) {
+    const def: FieldDefinition = typeof field === 'string'
+      ? { type: field }
+      : field
+
+    if (def.optional || def.default !== undefined) {
+      optionalFields.push(name)
+    } else {
+      requiredFields.push(name)
+    }
+  }
+
+  return {
+    name: definition.name as TName,
+    definition,
+    schema: schema as Type<Record<string, unknown>>,
+    createSchema: createSchema as Type<Record<string, unknown>>,
+    updateSchema: updateSchema as Type<Record<string, unknown>>,
+    querySchema: querySchema as Type<Record<string, unknown>>,
+    infer: {} as Record<string, unknown>,
+    autoFields,
+    requiredFields,
+    optionalFields,
+  }
+}
+
+/**
+ * Create a reference field to another entity
+ */
+export function ref(
+  entity: string | { name: string },
+  options?: {
+    field?: string
+    onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action'
+    optional?: boolean
+  }
+): FieldDefinition {
+  const entityName = typeof entity === 'string' ? entity : entity.name
+  const result: FieldDefinition = {
+    type: 'string.uuid',
+    db: {
+      references: {
+        entity: entityName,
+        field: options?.field ?? 'id',
+        onDelete: options?.onDelete ?? 'restrict',
+      },
+    },
+  }
+  if (options?.optional !== undefined) {
+    result.optional = options.optional
+  }
+  return result
+}
+
+/**
+ * Create an enum field from a list of values
+ */
+export function enumField<T extends string>(
+  values: readonly T[],
+  options?: { default?: T; optional?: boolean }
+): FieldDefinition {
+  const typeStr = values.map(v => `'${v}'`).join(' | ')
+  const result: FieldDefinition = {
+    type: typeStr as `'${string}'`,
+  }
+  if (options?.default !== undefined) {
+    result.default = options.default
+  }
+  if (options?.optional !== undefined) {
+    result.optional = options.optional
+  }
+  return result
+}
+
+/**
+ * Create a JSON field
+ */
+export function jsonField<T = Record<string, unknown>>(
+  options?: { optional?: boolean; default?: T }
+): FieldDefinition {
+  const result: FieldDefinition = {
+    type: 'json',
+  }
+  if (options?.optional !== undefined) {
+    result.optional = options.optional
+  }
+  if (options?.default !== undefined) {
+    result.default = options.default
+  }
+  return result
+}
+
+/**
+ * Create a decimal field with precision
+ */
+export function decimal(
+  precision: number,
+  scale: number,
+  options?: { min?: number; max?: number; optional?: boolean }
+): FieldDefinition {
+  const result: FieldDefinition = {
+    type: 'number',
+    db: {
+      precision,
+      scale,
+    },
+  }
+  if (options?.min !== undefined) {
+    result.min = options.min
+  }
+  if (options?.max !== undefined) {
+    result.max = options.max
+  }
+  if (options?.optional !== undefined) {
+    result.optional = options.optional
+  }
+  return result
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @parsrun/entity
+ *
+ * Single-source entity definitions for Pars framework.
+ * Define once, generate ArkType schemas and Drizzle tables.
+ *
+ * @example
+ * ```typescript
+ * import { defineEntity, ref, enumField } from '@parsrun/entity'
+ * import { toPgTable } from '@parsrun/entity/pg'
+ *
+ * // Define entity
+ * const Product = defineEntity({
+ *   name: 'products',
+ *   tenant: true,
+ *   timestamps: true,
+ *   softDelete: true,
+ *   fields: {
+ *     name: 'string >= 1',
+ *     slug: 'string',
+ *     description: { type: 'string', optional: true },
+ *     price: { type: 'number', min: 0 },
+ *     stock: { type: 'number.integer', min: 0, default: 0 },
+ *     status: enumField(['draft', 'active', 'archived'], { default: 'draft' }),
+ *     categoryId: ref('categories', { onDelete: 'set null', optional: true }),
+ *   },
+ *   indexes: [
+ *     { fields: ['tenantId', 'slug'], unique: true },
+ *     { fields: ['tenantId', 'status'] },
+ *   ],
+ * })
+ *
+ * // Use ArkType schemas
+ * const input = Product.createSchema(requestBody)
+ * if (input instanceof type.errors) throw new ValidationError(input)
+ *
+ * // Generate Drizzle table
+ * const productsTable = toPgTable(Product)
+ * await db.insert(productsTable).values({ tenantId, ...input })
+ * ```
+ */
+
+export { defineEntity, ref, enumField, jsonField, decimal } from './define.js'
+
+export type {
+  FieldType,
+  FieldDefinition,
+  SimpleFieldDefinition,
+  Field,
+  IndexDefinition,
+  EntityDefinition,
+  EntitySchemas,
+  Entity,
+  DrizzleOptions,
+  InferEntity,
+  InferCreateInput,
+  InferUpdateInput,
+} from './types.js'
+
+// Re-export arktype type function for convenience
+export { type } from 'arktype'

package/src/pg.ts

@@ -0,0 +1,224 @@
+/**
+ * PostgreSQL Drizzle table generation from entity definitions
+ */
+import {
+  pgTable,
+  uuid,
+  text,
+  integer,
+  boolean,
+  timestamp,
+  numeric,
+  json,
+  index,
+  uniqueIndex,
+} from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+import type { Entity, Field, FieldDefinition } from './types.js'
+
+/**
+ * Convert field definition to Drizzle column builder
+ */
+function fieldToColumn(name: string, field: Field) {
+  const def: FieldDefinition = typeof field === 'string' ? { type: field } : field
+
+  const columnName = def.db?.column ?? toSnakeCase(name)
+  let column: any
+
+  // Determine column type based on field type
+  const fieldType = def.type.split(' ')[0] ?? 'string'
+
+  switch (fieldType) {
+    case 'string.uuid':
+      column = uuid(columnName)
+      break
+
+    case 'string.email':
+    case 'string.url':
+    case 'string':
+      column = text(columnName)
+      break
+
+    case 'number.integer':
+      column = integer(columnName)
+      break
+
+    case 'number':
+      if (def.db?.precision) {
+        column = numeric(columnName, {
+          precision: def.db.precision,
+          scale: def.db.scale ?? 2,
+        })
+      } else {
+        column = numeric(columnName)
+      }
+      break
+
+    case 'boolean':
+      column = boolean(columnName)
+      break
+
+    case 'Date':
+      column = timestamp(columnName, { withTimezone: true })
+      break
+
+    case 'json':
+      column = json(columnName)
+      break
+
+    default:
+      // Union types like "'draft' | 'active'" become text
+      column = text(columnName)
+  }
+
+  // Apply modifiers
+  if (!def.optional && def.default === undefined) {
+    column = column.notNull()
+  }
+
+  if (def.default !== undefined) {
+    column = column.default(def.default)
+  }
+
+  return column
+}
+
+/**
+ * Convert camelCase to snake_case
+ */
+function toSnakeCase(str: string): string {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)
+}
+
+/**
+ * Generate a Drizzle pgTable from an entity definition
+ */
+export function toPgTable<E extends Entity<string, Record<string, Field>, unknown>>(
+  entity: E,
+  tableRefs?: Record<string, any>
+): any {
+  const def = entity.definition
+  const columns: Record<string, any> = {}
+
+  // Add id column
+  columns['id'] = uuid('id').primaryKey().defaultRandom()
+
+  // Add tenantId if tenant-scoped
+  if (def.tenant) {
+    const tenantsTable = tableRefs?.['tenants']
+    if (tenantsTable) {
+      columns['tenantId'] = uuid('tenant_id')
+        .notNull()
+        .references(() => tenantsTable.id, { onDelete: 'cascade' })
+    } else {
+      columns['tenantId'] = uuid('tenant_id').notNull()
+    }
+  }
+
+  // Add user-defined fields
+  for (const [name, field] of Object.entries(def.fields)) {
+    const fieldDef: FieldDefinition = typeof field === 'string' ? { type: field } : field
+
+    // Handle references
+    if (fieldDef.db?.references && tableRefs) {
+      const refTable = tableRefs[fieldDef.db.references.entity]
+      if (refTable) {
+        const refField = fieldDef.db.references.field ?? 'id'
+        const onDelete = fieldDef.db.references.onDelete ?? 'restrict'
+
+        let col = uuid(toSnakeCase(name)).references(() => refTable[refField], { onDelete })
+        if (!fieldDef.optional) {
+          col = col.notNull()
+        }
+        columns[name] = col
+      } else {
+        columns[name] = fieldToColumn(name, field)
+      }
+    } else {
+      columns[name] = fieldToColumn(name, field)
+    }
+  }
+
+  // Add timestamp fields
+  if (def.timestamps) {
+    columns['insertedAt'] = timestamp('inserted_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+
+    columns['updatedAt'] = timestamp('updated_at', { withTimezone: true })
+      .notNull()
+      .defaultNow()
+      .$onUpdate(() => new Date())
+  }
+
+  // Add soft delete field
+  if (def.softDelete) {
+    columns['deletedAt'] = timestamp('deleted_at', { withTimezone: true })
+  }
+
+  // Create table with indexes
+  return pgTable(def.name, columns, (t: any) => {
+    const indexes: Record<string, any> = {}
+
+    // Add indexes from definition
+    if (def.indexes) {
+      for (const idx of def.indexes) {
+        const idxName = idx.name ?? `${def.name}_${idx.fields.join('_')}_idx`
+        const idxColumns = idx.fields.map((f) => t[f]).filter(Boolean)
+
+        if (idxColumns.length === 0) continue
+
+        if (idx.unique) {
+          if (idx.where) {
+            indexes[idxName] = uniqueIndex(idxName)
+              .on(...(idxColumns as [any, ...any[]]))
+              .where(sql.raw(idx.where))
+          } else {
+            indexes[idxName] = uniqueIndex(idxName).on(...(idxColumns as [any, ...any[]]))
+          }
+        } else {
+          if (idx.where) {
+            indexes[idxName] = index(idxName)
+              .on(...(idxColumns as [any, ...any[]]))
+              .where(sql.raw(idx.where))
+          } else {
+            indexes[idxName] = index(idxName).on(...(idxColumns as [any, ...any[]]))
+          }
+        }
+      }
+    }
+
+    // Add default tenant index if tenant-scoped
+    if (def.tenant && t.tenantId) {
+      const tenantIdxName = `${def.name}_tenant_id_idx`
+      if (!indexes[tenantIdxName]) {
+        indexes[tenantIdxName] = index(tenantIdxName).on(t.tenantId)
+      }
+    }
+
+    return indexes
+  })
+}
+
+/**
+ * Create multiple tables with resolved references
+ */
+export function createPgSchema<
+  T extends Record<string, Entity<string, Record<string, Field>, unknown>>,
+>(entities: T): { [K in keyof T]: any } {
+  const tables: Record<string, any> = {}
+
+  // First pass: create tables without references
+  for (const [key, entity] of Object.entries(entities)) {
+    tables[key] = toPgTable(entity)
+  }
+
+  // Second pass: recreate tables with resolved references
+  for (const [key, entity] of Object.entries(entities)) {
+    tables[key] = toPgTable(entity, tables)
+  }
+
+  return tables as { [K in keyof T]: any }
+}
+
+export { toPgTable as toTable }