@sqldoc/templates 0.0.1

package/src/json-schema/index.ts

@@ -0,0 +1,351 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, type EnrichedColumn, enrichRealm } from '../helpers/enrich.ts'
+import { toPascalCase } from '../helpers/naming.ts'
+
+export const configSchema = {
+  mode: {
+    type: 'enum',
+    values: ['per-table', 'bundled'],
+    description: 'Output one file per table or a single bundled file (default: bundled)',
+  },
+  $id: {
+    type: 'string',
+    description: 'Schema ID base URI (e.g. https://example.com/schemas)',
+  },
+} as const
+
+const PG_TO_JSON_SCHEMA: Record<string, { type?: string; format?: string }> = {
+  // Numeric -- integers
+  smallint: { type: 'integer' },
+  int2: { type: 'integer' },
+  integer: { type: 'integer' },
+  int: { type: 'integer' },
+  int4: { type: 'integer' },
+  bigint: { type: 'integer' },
+  int8: { type: 'integer' },
+  serial: { type: 'integer' },
+  serial4: { type: 'integer' },
+  bigserial: { type: 'integer' },
+  serial8: { type: 'integer' },
+  smallserial: { type: 'integer' },
+  serial2: { type: 'integer' },
+
+  // Numeric -- floats
+  real: { type: 'number' },
+  float4: { type: 'number' },
+  'double precision': { type: 'number' },
+  float8: { type: 'number' },
+  numeric: { type: 'number' },
+  decimal: { type: 'number' },
+  money: { type: 'string' },
+
+  // String
+  text: { type: 'string' },
+  varchar: { type: 'string' },
+  'character varying': { type: 'string' },
+  char: { type: 'string' },
+  character: { type: 'string' },
+  name: { type: 'string' },
+  citext: { type: 'string' },
+
+  // Boolean
+  boolean: { type: 'boolean' },
+  bool: { type: 'boolean' },
+
+  // Date/Time
+  timestamp: { type: 'string', format: 'date-time' },
+  'timestamp without time zone': { type: 'string', format: 'date-time' },
+  timestamptz: { type: 'string', format: 'date-time' },
+  'timestamp with time zone': { type: 'string', format: 'date-time' },
+  date: { type: 'string', format: 'date' },
+  time: { type: 'string', format: 'time' },
+  'time without time zone': { type: 'string', format: 'time' },
+  timetz: { type: 'string', format: 'time' },
+  'time with time zone': { type: 'string', format: 'time' },
+  interval: { type: 'string', format: 'duration' },
+
+  // Binary
+  bytea: { type: 'string', format: 'byte' },
+
+  // JSON
+  json: {},
+  jsonb: {},
+
+  // UUID
+  uuid: { type: 'string', format: 'uuid' },
+
+  // Network
+  inet: { type: 'string', format: 'ipv4' },
+  cidr: { type: 'string' },
+  macaddr: { type: 'string' },
+  macaddr8: { type: 'string' },
+
+  // Other
+  xml: { type: 'string' },
+  tsvector: { type: 'string' },
+  tsquery: { type: 'string' },
+  oid: { type: 'integer' },
+}
+
+function pgToJsonSchema(pgType: string): Record<string, unknown> {
+  const normalized = pgType.toLowerCase().trim()
+
+  // Arrays
+  if (normalized.endsWith('[]')) {
+    return { type: 'array', items: pgToJsonSchema(normalized.slice(0, -2)) }
+  }
+  if (normalized.startsWith('_')) {
+    return { type: 'array', items: pgToJsonSchema(normalized.slice(1)) }
+  }
+
+  // Strip length specifiers
+  const baseType = normalized.replace(/\(\d+(?:,\s*\d+)?\)/, '').trim()
+
+  const mapped = PG_TO_JSON_SCHEMA[baseType]
+  if (mapped) return { ...mapped }
+
+  // JSON types -- no type constraint (any valid JSON)
+  if (baseType === 'json' || baseType === 'jsonb') return {}
+
+  return { type: 'string' }
+}
+
+function applyValidation(prop: Record<string, unknown>, col: EnrichedColumn): void {
+  for (const t of col.tags) {
+    if (t.namespace !== 'validate') continue
+
+    if (t.tag === 'notEmpty') {
+      if (prop.type === 'string') prop.minLength = 1
+      if (prop.type === 'array') prop.minItems = 1
+    } else if (t.tag === 'email') {
+      prop.format = 'email'
+    } else if (t.tag === 'length') {
+      const args = t.args as Record<string, unknown>
+      if (args.min !== undefined) prop.minLength = Number(args.min)
+      if (args.max !== undefined) prop.maxLength = Number(args.max)
+    } else if (t.tag === 'range') {
+      const args = t.args as Record<string, unknown>
+      if (args.min !== undefined) prop.minimum = Number(args.min)
+      if (args.max !== undefined) prop.maximum = Number(args.max)
+    } else if (t.tag === 'pattern') {
+      const pattern = Array.isArray(t.args) ? t.args[0] : undefined
+      if (pattern) prop.pattern = String(pattern)
+    } else if (t.tag === 'min') {
+      const val = Array.isArray(t.args) ? t.args[0] : undefined
+      if (val !== undefined) {
+        if (prop.type === 'string') prop.minLength = Number(val)
+        else prop.minimum = Number(val)
+      }
+    } else if (t.tag === 'max') {
+      const val = Array.isArray(t.args) ? t.args[0] : undefined
+      if (val !== undefined) {
+        if (prop.type === 'string') prop.maxLength = Number(val)
+        else prop.maximum = Number(val)
+      }
+    }
+  }
+}
+
+function buildTableSchema(
+  table: ReturnType<typeof activeTables>[number],
+  baseId?: string,
+  _enumDefs?: Map<string, string[]>,
+): Record<string, unknown> {
+  const required: string[] = []
+  const properties: Record<string, Record<string, unknown>> = {}
+
+  for (const col of table.columns) {
+    let prop: Record<string, unknown>
+
+    if (col.category === 'enum' && col.enumValues?.length) {
+      prop = { type: 'string', enum: col.enumValues }
+    } else {
+      prop = pgToJsonSchema(col.pgType)
+    }
+
+    if (!col.nullable) required.push(col.name)
+
+    applyValidation(prop, col)
+
+    properties[col.name] = prop
+  }
+
+  const schema: Record<string, unknown> = {
+    type: 'object',
+    properties,
+  }
+
+  if (required.length > 0) schema.required = required
+  if (baseId) schema.$id = `${baseId}/${table.name}`
+
+  return schema
+}
+
+function buildViewSchema(
+  view: { pascalName: string; name: string; columns: EnrichedColumn[] },
+  baseId?: string,
+): Record<string, unknown> {
+  const required: string[] = []
+  const properties: Record<string, Record<string, unknown>> = {}
+
+  for (const col of view.columns) {
+    let prop: Record<string, unknown>
+
+    if (col.category === 'enum' && col.enumValues?.length) {
+      prop = { type: 'string', enum: col.enumValues }
+    } else {
+      prop = pgToJsonSchema(col.pgType)
+    }
+
+    if (!col.nullable) required.push(col.name)
+
+    applyValidation(prop, col)
+
+    properties[col.name] = prop
+  }
+
+  const schema: Record<string, unknown> = {
+    type: 'object',
+    properties,
+    readOnly: true,
+  }
+
+  if (required.length > 0) schema.required = required
+  if (baseId) schema.$id = `${baseId}/${view.name}`
+
+  return schema
+}
+
+export default defineTemplate({
+  name: 'JSON Schema',
+  description: 'Generate JSON Schema definitions from SQL schema',
+  language: 'json',
+  configSchema,
+
+  generate(ctx) {
+    const config = ctx.config ?? {}
+    const schema = enrichRealm(ctx)
+    const tables = activeTables(schema)
+    const views = schema.views.filter((v) => !v.skipped)
+    const baseId = config.$id
+
+    // Collect composite types from columns
+    const composites = new Map<string, Array<{ name: string; type: string }>>()
+    for (const table of schema.tables) {
+      for (const col of table.columns) {
+        if (col.category === 'composite' && col.compositeFields?.length && !composites.has(col.pgType)) {
+          composites.set(col.pgType, col.compositeFields)
+        }
+      }
+    }
+
+    if (config.mode === 'per-table') {
+      const files = [
+        ...tables.map((table) => ({
+          path: `${table.name}.schema.json`,
+          content: `${JSON.stringify(
+            { $schema: 'https://json-schema.org/draft/2020-12/schema', ...buildTableSchema(table, baseId) },
+            null,
+            2,
+          )}\n`,
+        })),
+        ...views.map((view) => ({
+          path: `${view.name}.schema.json`,
+          content: `${JSON.stringify(
+            { $schema: 'https://json-schema.org/draft/2020-12/schema', ...buildViewSchema(view, baseId) },
+            null,
+            2,
+          )}\n`,
+        })),
+      ]
+      return { files }
+    }
+
+    // Bundled mode (default): all tables as $defs with top-level oneOf
+    const defs: Record<string, Record<string, unknown>> = {}
+
+    // Enum definitions
+    for (const e of schema.enums) {
+      defs[e.pascalName] = { type: 'string', enum: e.values }
+    }
+
+    // Composite type definitions
+    for (const [name, fields] of composites) {
+      const props: Record<string, Record<string, unknown>> = {}
+      const req: string[] = []
+      for (const f of fields) {
+        props[f.name] = pgToJsonSchema(f.type)
+        req.push(f.name)
+      }
+      const compSchema: Record<string, unknown> = { type: 'object', properties: props }
+      if (req.length > 0) compSchema.required = req
+      defs[toPascalCase(name)] = compSchema
+    }
+
+    for (const table of tables) {
+      defs[table.pascalName] = buildTableSchema(table, baseId)
+    }
+
+    for (const view of views) {
+      defs[view.pascalName] = buildViewSchema(view, baseId)
+    }
+
+    // Function schemas (skip trigger functions)
+    for (const fn of schema.functions) {
+      const retRaw = fn.returnType?.type?.toLowerCase() ?? ''
+      if (retRaw === 'trigger') continue
+
+      const params: Record<string, Record<string, unknown>> = {}
+      const paramRequired: string[] = []
+      for (const a of fn.args.filter((a) => !a.name?.startsWith('_') && (a as any).mode !== 'OUT')) {
+        const argName = a.name || 'arg'
+        params[argName] = pgToJsonSchema(a.type)
+        paramRequired.push(argName)
+      }
+
+      let returnSchema: Record<string, unknown>
+      if (retRaw.startsWith('setof ')) {
+        const tableName = retRaw.replace('setof ', '')
+        const table = schema.tables.find((t) => t.name === tableName)
+        if (table) {
+          returnSchema = { type: 'array', items: { $ref: `#/$defs/${table.pascalName}` } }
+        } else {
+          returnSchema = { type: 'array', items: pgToJsonSchema(tableName) }
+        }
+      } else if (fn.returnType) {
+        returnSchema = pgToJsonSchema(fn.returnType.type)
+      } else {
+        returnSchema = {}
+      }
+
+      const fnSchema: Record<string, unknown> = {
+        type: 'object',
+        properties: {
+          parameters: {
+            type: 'object',
+            properties: params,
+            ...(paramRequired.length > 0 ? { required: paramRequired } : {}),
+          },
+          returnType: returnSchema,
+        },
+      }
+
+      defs[fn.pascalName] = fnSchema
+    }
+
+    const bundled: Record<string, unknown> = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $defs: defs,
+    }
+    if (baseId) bundled.$id = baseId
+
+    return {
+      files: [
+        {
+          path: 'schema.json',
+          content: `${JSON.stringify(bundled, null, 2)}\n`,
+        },
+      ],
+    }
+  },
+})

package/src/json-schema/test/.gitignore

@@ -0,0 +1,6 @@
+# Generated by codegen — only Dockerfile and test scripts are tracked
+*
+!.gitignore
+!Dockerfile
+!test.*
+!Test.*

package/src/json-schema/test/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:23-slim
+WORKDIR /app
+COPY . .
+RUN npm init -y && npm install ajv@8 ajv-formats@3 --save-dev
+RUN node -e " \
+  const Ajv = require('ajv/dist/2020'); \
+  const addFormats = require('ajv-formats'); \
+  const schema = require('./schema.json'); \
+  const ajv = new Ajv({ allErrors: true }); \
+  addFormats(ajv); \
+  for (const [name, def] of Object.entries(schema.\$defs || {})) { \
+    const valid = ajv.validateSchema(def); \
+    if (!valid) { console.error('INVALID:', name, ajv.errors); process.exit(1); } \
+    console.log('OK:', name); \
+  } \
+  console.log('All schemas valid'); \
+"
+CMD ["echo", "ok"]

package/src/knex/index.ts

@@ -0,0 +1,168 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, enrichRealm } from '../helpers/enrich.ts'
+import { toCamelCase, toPascalCase } from '../helpers/naming.ts'
+import { pgToTs, type TsTypeOptions } from '../types/pg-to-ts.ts'
+
+export const configSchema = {
+  dateType: {
+    type: 'enum',
+    values: ['Date', 'dayjs', 'luxon', 'string'],
+    description: 'How to represent date/time types',
+  },
+  bigintType: {
+    type: 'enum',
+    values: ['number', 'bigint', 'string'],
+    description: 'How to represent bigint/bigserial columns',
+  },
+} as const
+
+export default defineTemplate({
+  name: 'Knex Table Types',
+  description: 'Generate TypeScript table interfaces with Knex module augmentation for type-safe queries',
+  language: 'typescript',
+  configSchema,
+
+  generate(ctx) {
+    const config = ctx.config ?? {}
+    const options: TsTypeOptions = {
+      dateType: config.dateType,
+      bigintType: config.bigintType,
+      nullableStyle: 'null-union',
+    }
+
+    const schema = enrichRealm(ctx)
+    const lines: string[] = [
+      '// Generated by @sqldoc/templates/knex -- DO NOT EDIT',
+      '',
+      "import type { Knex } from 'knex'",
+      '',
+    ]
+
+    // Enums
+    for (const e of schema.enums) {
+      const values = e.values.map((v) => `'${v}'`).join(' | ')
+      lines.push(`export type ${e.pascalName} = ${values}`)
+      lines.push('')
+    }
+
+    // Composite types (collected from columns)
+    const composites = new Map<string, Array<{ name: string; type: string }>>()
+    for (const table of schema.tables) {
+      for (const col of table.columns) {
+        if (col.category === 'composite' && col.compositeFields?.length && !composites.has(col.pgType)) {
+          composites.set(col.pgType, col.compositeFields)
+        }
+      }
+    }
+    for (const [name, fields] of composites) {
+      const typeName = toPascalCase(name)
+      lines.push(`export interface ${typeName} {`)
+      for (const f of fields) {
+        lines.push(`  ${toCamelCase(f.name)}: ${pgToTs(f.type, false, options)}`)
+      }
+      lines.push('}')
+      lines.push('')
+    }
+
+    // Generate per-table interfaces
+    const tableEntries: string[] = []
+
+    for (const table of activeTables(schema)) {
+      const interfaceName = `${table.pascalName}Table`
+
+      lines.push(`export interface ${interfaceName} {`)
+
+      for (const col of table.columns) {
+        const tsType = resolveType(col, options)
+        lines.push(`  ${col.name}: ${tsType}`)
+      }
+
+      lines.push('}')
+      lines.push('')
+
+      tableEntries.push(`    ${table.name}: ${interfaceName}`)
+    }
+
+    // Views (read-only)
+    const viewEntries: string[] = []
+
+    for (const view of schema.views.filter((v) => !v.skipped)) {
+      const interfaceName = `${view.pascalName}View`
+
+      lines.push(`/** Read-only (from view) */`)
+      lines.push(`export interface ${interfaceName} {`)
+
+      for (const col of view.columns) {
+        const tsType = resolveType(col, options)
+        lines.push(`  ${col.name}: ${tsType}`)
+      }
+
+      lines.push('}')
+      lines.push('')
+
+      viewEntries.push(`    ${view.name}: ${interfaceName}`)
+    }
+
+    // Knex module augmentation for type-safe table map
+    lines.push("declare module 'knex/types/tables' {")
+    lines.push('  interface Tables {')
+    for (const entry of tableEntries) {
+      lines.push(entry)
+    }
+    for (const entry of viewEntries) {
+      lines.push(entry)
+    }
+    lines.push('  }')
+    lines.push('}')
+    lines.push('')
+
+    // Functions (skip trigger functions)
+    for (const fn of schema.functions) {
+      const retRaw = fn.returnType?.type?.toLowerCase() ?? ''
+      if (retRaw === 'trigger') continue
+
+      const params = fn.args
+        .filter((a) => !a.name?.startsWith('_') && (a as any).mode !== 'OUT')
+        .map((a) => {
+          const argType = pgToTs(a.type, false, options, a.category as any)
+          return `${toCamelCase(a.name || 'arg')}: ${argType}`
+        })
+        .join(', ')
+
+      let retType: string
+      if (retRaw.startsWith('setof ')) {
+        const tableName = retRaw.replace('setof ', '')
+        const table = schema.tables.find((t) => t.name === tableName)
+        retType = table ? `${table.pascalName}Table[]` : `${pgToTs(tableName, false, options)}[]`
+      } else if (fn.returnType) {
+        retType = pgToTs(fn.returnType.type, false, options, fn.returnType.category as any)
+      } else {
+        retType = 'void'
+      }
+
+      lines.push(`export type ${fn.pascalName} = (${params}) => ${retType}`)
+      lines.push('')
+    }
+
+    return {
+      files: [
+        {
+          path: 'database.ts',
+          content: lines.join('\n'),
+        },
+      ],
+    }
+
+    function resolveType(col: any, options: TsTypeOptions): string {
+      if (col.typeOverride) return col.typeOverride
+      if (col.category === 'enum' && col.enumValues?.length) {
+        return col.nullable ? `${toPascalCase(col.pgType)} | null` : toPascalCase(col.pgType)
+      }
+      if (col.category === 'composite' && col.compositeFields?.length) {
+        const compositeType = toPascalCase(col.pgType)
+        return col.nullable ? `${compositeType} | null` : compositeType
+      }
+      return pgToTs(col.pgType, col.nullable, options, col.category)
+    }
+  },
+})

package/src/knex/test/.gitignore

@@ -0,0 +1,6 @@
+# Generated by codegen — only Dockerfile and test scripts are tracked
+*
+!.gitignore
+!Dockerfile
+!test.*
+!Test.*

package/src/knex/test/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:23-slim
+WORKDIR /app
+COPY . .
+RUN npm init -y && npm pkg set type=module && npm install typescript@5 knex@3 pg @types/pg @types/node --save-dev
+# Note: knex module augmentation (knex/types/tables) doesn't typecheck under nodenext.
+# Skip tsc and focus on the runtime integration test.
+CMD ["node", "--experimental-strip-types", "test.ts"]

package/src/knex/test/test.ts

@@ -0,0 +1,75 @@
+/**
+ * Integration test for @sqldoc/templates/knex
+ * Connects to real Postgres via Knex, verifies generated table types work.
+ */
+import knex from 'knex'
+// Import to ensure the module augmentation is loaded
+import type {} from './database.ts'
+
+const DATABASE_URL = process.env.DATABASE_URL
+if (!DATABASE_URL) {
+  console.error('DATABASE_URL not set')
+  process.exit(1)
+}
+
+const db = knex({
+  client: 'pg',
+  connection: DATABASE_URL,
+})
+
+let failed = 0
+function assert(condition: boolean, msg: string) {
+  if (!condition) {
+    console.error(`FAIL: ${msg}`)
+    failed++
+  } else {
+    console.log(`  ok: ${msg}`)
+  }
+}
+
+async function run() {
+  try {
+    console.log('--- knex integration test ---')
+
+    // 1. Query known seeded user using Knex's type-safe table method
+    const users = await db('users').where({ id: 1 })
+    const user = users[0]
+
+    assert(user.email === 'test@example.com', 'user email matches')
+    assert(user.name === 'Test User', 'user name matches')
+    assert(user.is_active === true, 'user is_active matches')
+
+    // 2. Query known seeded post
+    const posts = await db('posts').where({ id: 1 })
+    assert(posts.length === 1, 'seeded post found')
+    assert(posts[0].title === 'Hello World', 'post title matches')
+
+    // 3. Insert a new post
+    await db('posts').insert({
+      user_id: 1,
+      title: 'Post from knex',
+      body: 'test body',
+      view_count: 0,
+    })
+
+    // 4. Read it back
+    const newPosts = await db('posts').where({ title: 'Post from knex' })
+    assert(newPosts.length === 1, 'inserted post found')
+    assert(newPosts[0].title === 'Post from knex', 'inserted post title matches')
+    // pg returns bigint columns as strings; use Number() for comparison
+    assert(Number(newPosts[0].user_id) === 1, 'inserted post user_id matches')
+
+    if (failed > 0) {
+      console.error(`\n${failed} assertion(s) failed`)
+      process.exit(1)
+    }
+    console.log('\nAll assertions passed!')
+  } finally {
+    await db.destroy()
+  }
+}
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})