@sqldoc/templates 0.0.1

package/src/typescript/index.ts

@@ -0,0 +1,168 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, enrichRealm } from '../helpers/enrich.ts'
+import { toCamelCase } from '../helpers/naming.ts'
+import { pgToTs, type TsTypeOptions } from '../types/pg-to-ts.ts'
+
+export const configSchema = {
+  dateType: {
+    type: 'enum',
+    values: ['Date', 'temporal', 'dayjs', 'luxon', 'string'],
+    description: 'How to represent date/time types',
+  },
+  nullableStyle: {
+    type: 'enum',
+    values: ['optional', 'null-union'],
+    description: 'Use optional properties (?) or explicit null unions (| null)',
+  },
+  bigintType: {
+    type: 'enum',
+    values: ['number', 'bigint', 'string'],
+    description: 'How to represent bigint/bigserial columns',
+  },
+} as const
+
+export default defineTemplate({
+  name: 'TypeScript Interfaces',
+  description: 'Generate TypeScript interface definitions from SQL schema',
+  language: 'typescript',
+  configSchema,
+
+  generate(ctx) {
+    const config = ctx.config ?? {}
+    const options: TsTypeOptions = {
+      dateType: config.dateType,
+      nullableStyle: config.nullableStyle,
+      bigintType: config.bigintType,
+    }
+
+    const schema = enrichRealm(ctx)
+    const lines: string[] = ['// Generated by @sqldoc/templates/typescript -- DO NOT EDIT', '']
+
+    // When using Temporal API date types, emit a global declaration so the code typechecks
+    // even without a full Temporal polyfill type package installed.
+    if (options.dateType === 'temporal') {
+      lines.push('declare global {')
+      lines.push('  namespace Temporal {')
+      lines.push('    interface PlainDate { toString(): string }')
+      lines.push('    interface PlainTime { toString(): string }')
+      lines.push('    interface PlainDateTime { toString(): string }')
+      lines.push('    interface ZonedDateTime { toString(): string }')
+      lines.push('    interface Duration { toString(): string }')
+      lines.push('  }')
+      lines.push('}')
+      lines.push('')
+    }
+
+    // Enums
+    for (const e of schema.enums) {
+      lines.push(`export type ${e.pascalName} = ${e.values.map((v) => `'${v}'`).join(' | ')}`)
+      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 =
+        name.charAt(0).toUpperCase() + name.slice(1).replace(/_([a-z])/g, (_: string, c: string) => c.toUpperCase())
+      lines.push(`export interface ${typeName} {`)
+      for (const f of fields) {
+        lines.push(`  ${toCamelCase(f.name)}: ${pgToTs(f.type, false, options)}`)
+      }
+      lines.push('}')
+      lines.push('')
+    }
+
+    // Tables
+    for (const table of activeTables(schema)) {
+      lines.push(`export interface ${table.pascalName} {`)
+      for (const col of table.columns) {
+        const tsType = resolveType(col, config, options)
+        const propName = toCamelCase(col.name)
+        if (col.nullable && config.nullableStyle !== 'null-union') {
+          lines.push(`  ${propName}?: ${tsType}`)
+        } else {
+          lines.push(`  ${propName}: ${tsType}`)
+        }
+      }
+      lines.push('}')
+      lines.push('')
+    }
+
+    // Views (read-only)
+    for (const view of schema.views.filter((v) => !v.skipped)) {
+      lines.push(`/** Read-only (from view) */`)
+      lines.push(`export interface ${view.pascalName} {`)
+      for (const col of view.columns) {
+        const tsType = resolveType(col, config, options)
+        const propName = toCamelCase(col.name)
+        if (col.nullable && config.nullableStyle !== 'null-union') {
+          lines.push(`  ${propName}?: ${tsType}`)
+        } else {
+          lines.push(`  ${propName}: ${tsType}`)
+        }
+      }
+      lines.push('}')
+      lines.push('')
+    }
+
+    // Functions (skip trigger functions — they're not user-callable)
+    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 ')) {
+        // RETURNS SETOF tablename → Table[]
+        const tableName = retRaw.replace('setof ', '')
+        const table = schema.tables.find((t) => t.name === tableName)
+        retType = table ? `${table.pascalName}[]` : `${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: 'models.ts',
+          content: lines.join('\n'),
+        },
+      ],
+    }
+
+    function resolveType(col: any, config: any, options: TsTypeOptions): string {
+      if (col.typeOverride) return col.typeOverride
+      const toPascal = (s: string) =>
+        s.charAt(0).toUpperCase() + s.slice(1).replace(/_([a-z])/g, (_: string, c: string) => c.toUpperCase())
+      if (col.category === 'enum' && col.enumValues?.length) {
+        const enumType = toPascal(col.pgType)
+        return col.nullable && config.nullableStyle === 'null-union' ? `${enumType} | null` : enumType
+      }
+      if (col.category === 'composite' && col.compositeFields?.length) {
+        const compositeType = toPascal(col.pgType)
+        return col.nullable && config.nullableStyle === 'null-union' ? `${compositeType} | null` : compositeType
+      }
+      return pgToTs(col.pgType, col.nullable && config.nullableStyle === 'null-union', options, col.category)
+    }
+  },
+})

package/src/typescript/test/.gitignore

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

package/src/typescript/test/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:23-slim
+WORKDIR /app
+COPY . .
+RUN npm init -y && npm pkg set type=module && npm install typescript@5 pg @types/pg @types/node --save-dev
+# Step 1: typecheck the generated models
+RUN npx tsc --noEmit --strict --esModuleInterop --module nodenext --moduleResolution nodenext models.ts
+# Step 2: run integration test against real DB
+CMD ["node", "--experimental-strip-types", "test.ts"]

package/src/typescript/test/test.ts

@@ -0,0 +1,89 @@
+/**
+ * Integration test for @sqldoc/templates/typescript
+ * Connects to real Postgres, verifies generated types work with actual data.
+ */
+import { Client } from 'pg'
+// Import the generated type -- file is copied from codegen output at test time
+import type { Users, Posts } from './models.ts'
+
+const DATABASE_URL = process.env.DATABASE_URL
+if (!DATABASE_URL) {
+  console.error('DATABASE_URL not set')
+  process.exit(1)
+}
+
+const client = new Client(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() {
+  await client.connect()
+
+  try {
+    console.log('--- typescript integration test ---')
+
+    // 1. Query known seeded user
+    const { rows: userRows } = await client.query('SELECT * FROM users WHERE id = 1')
+    const user = userRows[0]
+    assert(user.email === 'test@example.com', 'user email matches')
+    assert(user.name === 'Test User', 'user name matches')
+    assert(user.age === 30, 'user age matches')
+    assert(user.is_active === true, 'user is_active matches')
+
+    // Verify the type is assignable (compile-time check; runtime confirms shape)
+    const _typedUser: Partial<Users> = {
+      id: Number(user.id),
+      email: user.email,
+      name: user.name,
+      age: user.age,
+      isActive: user.is_active,
+    }
+    assert(typeof _typedUser.email === 'string', 'typed user email is string')
+
+    // 2. Query known seeded post
+    const { rows: postRows } = await client.query('SELECT * FROM posts WHERE id = 1')
+    assert(postRows.length === 1, 'seeded post found')
+    assert(postRows[0].title === 'Hello World', 'post title matches')
+
+    // Verify Posts type assignability
+    const _typedPost: Partial<Posts> = {
+      id: Number(postRows[0].id),
+      title: postRows[0].title,
+      body: postRows[0].body,
+    }
+    assert(typeof _typedPost.title === 'string', 'typed post title is string')
+
+    // 3. Insert a new post
+    await client.query(
+      "INSERT INTO posts (user_id, title, body, view_count) VALUES (1, 'Post from typescript', 'test body', 0)",
+    )
+
+    // 4. Read it back
+    const { rows: newPosts } = await client.query("SELECT * FROM posts WHERE title = 'Post from typescript'")
+    assert(newPosts.length === 1, 'inserted post found')
+    assert(newPosts[0].title === 'Post from typescript', '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 client.end()
+  }
+}
+
+run().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/src/xsd/index.ts

@@ -0,0 +1,191 @@
+import { defineTemplate } from '@sqldoc/ns-codegen'
+import { activeTables, type EnrichedColumn, enrichRealm } from '../helpers/enrich.ts'
+import { toPascalCase } from '../helpers/naming.ts'
+
+const PG_TO_XSD: Record<string, string> = {
+  smallint: 'xs:short',
+  int2: 'xs:short',
+  integer: 'xs:int',
+  int: 'xs:int',
+  int4: 'xs:int',
+  bigint: 'xs:long',
+  int8: 'xs:long',
+  serial: 'xs:int',
+  serial4: 'xs:int',
+  bigserial: 'xs:long',
+  serial8: 'xs:long',
+  smallserial: 'xs:short',
+  serial2: 'xs:short',
+  real: 'xs:float',
+  float4: 'xs:float',
+  'double precision': 'xs:double',
+  float8: 'xs:double',
+  numeric: 'xs:decimal',
+  decimal: 'xs:decimal',
+  money: 'xs:decimal',
+  text: 'xs:string',
+  varchar: 'xs:string',
+  'character varying': 'xs:string',
+  char: 'xs:string',
+  character: 'xs:string',
+  name: 'xs:string',
+  citext: 'xs:string',
+  boolean: 'xs:boolean',
+  bool: 'xs:boolean',
+  timestamp: 'xs:dateTime',
+  'timestamp without time zone': 'xs:dateTime',
+  timestamptz: 'xs:dateTime',
+  'timestamp with time zone': 'xs:dateTime',
+  date: 'xs:date',
+  time: 'xs:time',
+  'time without time zone': 'xs:time',
+  timetz: 'xs:time',
+  'time with time zone': 'xs:time',
+  interval: 'xs:duration',
+  bytea: 'xs:base64Binary',
+  json: 'xs:string',
+  jsonb: 'xs:string',
+  uuid: 'xs:string',
+  inet: 'xs:string',
+  xml: 'xs:string',
+}
+
+function pgToXsd(pgType: string): string {
+  const base = pgType
+    .toLowerCase()
+    .replace(/\(\d+(?:,\s*\d+)?\)/, '')
+    .trim()
+  if (base.endsWith('[]') || base.startsWith('_')) return 'xs:string'
+  return PG_TO_XSD[base] ?? 'xs:string'
+}
+
+function buildRestrictions(col: EnrichedColumn): string[] {
+  const restrictions: string[] = []
+  for (const t of col.tags) {
+    if (t.namespace !== 'validate') continue
+    if (t.tag === 'notEmpty') restrictions.push('        <xs:minLength value="1"/>')
+    else if (t.tag === 'length') {
+      const args = t.args as Record<string, unknown>
+      if (args.min !== undefined) restrictions.push(`        <xs:minLength value="${args.min}"/>`)
+      if (args.max !== undefined) restrictions.push(`        <xs:maxLength value="${args.max}"/>`)
+    } else if (t.tag === 'range') {
+      const args = t.args as Record<string, unknown>
+      if (args.min !== undefined) restrictions.push(`        <xs:minInclusive value="${args.min}"/>`)
+      if (args.max !== undefined) restrictions.push(`        <xs:maxInclusive value="${args.max}"/>`)
+    } else if (t.tag === 'pattern') {
+      const pattern = Array.isArray(t.args) ? t.args[0] : undefined
+      if (pattern) restrictions.push(`        <xs:pattern value="${escapeXml(String(pattern))}"/>`)
+    }
+  }
+  return restrictions
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+export default defineTemplate({
+  name: 'XML Schema (XSD)',
+  description: 'Generate XML Schema Definition types from SQL schema',
+  language: 'xml',
+
+  generate(ctx) {
+    const schema = enrichRealm(ctx)
+    const lines: string[] = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!-- Generated by @sqldoc/templates/xsd. DO NOT EDIT -->',
+      '<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">',
+      '',
+    ]
+
+    // Enums as simpleType restrictions
+    for (const e of schema.enums) {
+      lines.push(`  <xs:simpleType name="${e.pascalName}">`)
+      lines.push(`    <xs:restriction base="xs:string">`)
+      for (const v of e.values) {
+        lines.push(`      <xs:enumeration value="${escapeXml(v)}"/>`)
+      }
+      lines.push(`    </xs:restriction>`)
+      lines.push(`  </xs:simpleType>`)
+      lines.push('')
+    }
+
+    for (const table of activeTables(schema)) {
+      lines.push(`  <xs:complexType name="${table.pascalName}">`)
+      lines.push('    <xs:sequence>')
+
+      for (const col of table.columns) {
+        if (col.category === 'enum' && col.enumValues?.length) {
+          // Reference the enum simpleType
+          const enumTypeName = toPascalCase(col.pgType)
+          lines.push(
+            `      <xs:element name="${col.camelName}" type="${enumTypeName}"${col.nullable ? ' minOccurs="0"' : ''}/>`,
+          )
+        } else {
+          const xsdType = pgToXsd(col.pgType)
+          const restrictions = buildRestrictions(col)
+
+          if (restrictions.length > 0) {
+            lines.push(`      <xs:element name="${col.camelName}"${col.nullable ? ' minOccurs="0"' : ''}>`)
+            lines.push('        <xs:simpleType>')
+            lines.push(`          <xs:restriction base="${xsdType}">`)
+            lines.push(...restrictions.map((r) => `  ${r}`))
+            lines.push('          </xs:restriction>')
+            lines.push('        </xs:simpleType>')
+            lines.push('      </xs:element>')
+          } else {
+            lines.push(
+              `      <xs:element name="${col.camelName}" type="${xsdType}"${col.nullable ? ' minOccurs="0"' : ''}/>`,
+            )
+          }
+        }
+      }
+
+      lines.push('    </xs:sequence>')
+      lines.push('  </xs:complexType>')
+      lines.push('')
+    }
+
+    // Views (read-only)
+    for (const view of schema.views.filter((v) => !v.skipped)) {
+      lines.push(`  <!-- Read-only (from view) -->`)
+      lines.push(`  <xs:complexType name="${view.pascalName}">`)
+      lines.push('    <xs:sequence>')
+
+      for (const col of view.columns) {
+        if (col.category === 'enum' && col.enumValues?.length) {
+          const enumTypeName = toPascalCase(col.pgType)
+          lines.push(
+            `      <xs:element name="${col.camelName}" type="${enumTypeName}"${col.nullable ? ' minOccurs="0"' : ''}/>`,
+          )
+        } else {
+          const xsdType = pgToXsd(col.pgType)
+          const restrictions = buildRestrictions(col)
+
+          if (restrictions.length > 0) {
+            lines.push(`      <xs:element name="${col.camelName}"${col.nullable ? ' minOccurs="0"' : ''}>`)
+            lines.push('        <xs:simpleType>')
+            lines.push(`          <xs:restriction base="${xsdType}">`)
+            lines.push(...restrictions.map((r) => `  ${r}`))
+            lines.push('          </xs:restriction>')
+            lines.push('        </xs:simpleType>')
+            lines.push('      </xs:element>')
+          } else {
+            lines.push(
+              `      <xs:element name="${col.camelName}" type="${xsdType}"${col.nullable ? ' minOccurs="0"' : ''}/>`,
+            )
+          }
+        }
+      }
+
+      lines.push('    </xs:sequence>')
+      lines.push('  </xs:complexType>')
+      lines.push('')
+    }
+
+    lines.push('</xs:schema>')
+    lines.push('')
+
+    return { files: [{ path: 'schema.xsd', content: lines.join('\n') }] }
+  },
+})

package/src/xsd/test/.gitignore

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

package/src/xsd/test/Dockerfile

@@ -0,0 +1,6 @@
+FROM alpine:3.20
+RUN apk add --no-cache libxml2-utils
+WORKDIR /app
+COPY . .
+RUN xmllint --noout schema.xsd
+CMD ["echo", "ok"]