ts-procedures 5.9.1 → 5.10.2

package/src/codegen/emit-types.ts

@@ -0,0 +1,158 @@
+export interface AjscOptions {
+  enumStyle?: 'union' | 'enum'
+  depluralize?: boolean
+  inlineTypes?: boolean
+  arrayItemNaming?: string | false
+  uncountableWords?: string[]
+  jsdoc?: boolean
+}
+
+let ajscValidated = false
+async function validateAjscFormat() {
+  if (ajscValidated) return
+  ajscValidated = true
+  const { TypescriptConverter } = await import('ajsc')
+  const probe = new TypescriptConverter({ type: 'string' }, { inlineTypes: true })
+  const probeCode = (probe.code as string).trim()
+  if (probeCode !== 'string') {
+    console.warn(`[ts-procedures-codegen] ajsc output format may have changed. Expected "string" for { type: "string" }, got: "${probeCode}"`)
+  }
+}
+
+async function resolveTypeBody(
+  schema: Record<string, unknown>,
+  options?: AjscOptions,
+): Promise<string> {
+  await validateAjscFormat()
+
+  const { TypescriptConverter } = await import('ajsc')
+
+  const converter = new TypescriptConverter(schema, {
+    ...options,
+    inlineTypes: true,
+  })
+
+  let code = (converter.code as string).trim()
+  if (!code) {
+    throw new Error(
+      `[ts-procedures-codegen] ajsc produced empty output. Schema: ${JSON.stringify(schema)}`
+    )
+  }
+  // Strip any 'export type X = ' or 'type X = ' prefix ajsc might add
+  code = code.replace(/^(?:export\s+)?type\s+\w+\s*=\s*/, '')
+  // Remove trailing semicolons and newlines
+  code = code.replace(/;\s*$/, '').trim()
+
+  return code
+}
+
+/**
+ * Converts a JSON Schema to a TypeScript type string using ajsc.
+ *
+ * Returns `export type ${typeName} = ${code}` where code is the inline type
+ * body from TypescriptConverter with inlineTypes: true.
+ *
+ * Returns undefined for undefined or null schema.
+ */
+export async function jsonSchemaToTypeString(
+  typeName: string,
+  schema: Record<string, unknown> | undefined,
+  options?: AjscOptions,
+): Promise<string | undefined> {
+  if (schema == null) return undefined
+  const code = await resolveTypeBody(schema, options)
+  return `export type ${typeName} = ${code}`
+}
+
+/**
+ * Converts a JSON Schema to a bare TypeScript type body using ajsc.
+ *
+ * Returns just the type literal (e.g., `{ id: string; }`) without any
+ * `export type Name =` wrapper. Used by flat mode in emit-scope.
+ *
+ * Returns undefined for undefined or null schema.
+ */
+export async function jsonSchemaToTypeBody(
+  schema: Record<string, unknown> | undefined,
+  options?: AjscOptions,
+): Promise<string | undefined> {
+  if (schema == null) return undefined
+  return resolveTypeBody(schema, options)
+}
+
+// ---------------------------------------------------------------------------
+// Extracted types (namespace mode — uses inlineTypes: false)
+// ---------------------------------------------------------------------------
+
+export interface ExtractedTypeOutput {
+  /** Extracted sub-type/enum declarations (e.g., `export type Address = { ... }`, `export enum Status { ... }`). */
+  declarations: string[]
+  /** The root type body (bare literal, e.g., `{ user: User; }`) without the `export type Root =` wrapper. */
+  body: string
+}
+
+/**
+ * Converts a JSON Schema to extracted TypeScript types using ajsc with
+ * `inlineTypes: false`. This produces named sub-types (objects, enums) that
+ * are separated from the root type body.
+ *
+ * Used in namespace mode where sub-types live naturally inside the namespace
+ * and ajsc formatting options (enumStyle, depluralize, jsdoc, etc.) take effect.
+ *
+ * Returns undefined for undefined or null schema.
+ */
+export async function jsonSchemaToExtractedTypes(
+  schema: Record<string, unknown> | undefined,
+  options?: AjscOptions,
+): Promise<ExtractedTypeOutput | undefined> {
+  if (schema == null) return undefined
+
+  await validateAjscFormat()
+
+  const { TypescriptConverter } = await import('ajsc')
+  const converter = new TypescriptConverter(schema, {
+    ...options,
+    inlineTypes: false,
+  })
+
+  const code = (converter.code as string).trim()
+  if (!code) {
+    throw new Error(
+      `[ts-procedures-codegen] ajsc produced empty output. Schema: ${JSON.stringify(schema)}`
+    )
+  }
+
+  // ajsc with inlineTypes: false produces blocks separated by blank lines:
+  //   export enum Status { Active = "active" }
+  //   export type Contact = { name: string; };
+  //   export type Root = { status: Status; contacts: Array<Contact>; };
+  //
+  // The Root type is always the last declaration.
+  const blocks = code.split(/\n\n+/).map((b) => b.trim()).filter(Boolean)
+
+  const declarations: string[] = []
+  let body = ''
+
+  for (const block of blocks) {
+    if (block.startsWith('export type Root')) {
+      // Strip "export type Root = " prefix and trailing ";"
+      body = block
+        .replace(/^export\s+type\s+Root\s*=\s*/, '')
+        .replace(/;\s*$/, '')
+        .trim()
+    } else {
+      // Sub-type or enum declaration — remove trailing ";" for consistency
+      declarations.push(block.replace(/;\s*$/, ''))
+    }
+  }
+
+  if (!body) {
+    // Fallback: treat whole output as inline body
+    body = code
+      .replace(/^(?:export\s+)?type\s+\w+\s*=\s*/, '')
+      .replace(/;\s*$/, '')
+      .trim()
+  }
+
+  return { declarations, body }
+}

package/src/codegen/group-routes.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { normalizeScope, scopeToCamelCase, groupRoutesByScope } from './group-routes.js'
+import type { AnyHttpRouteDoc } from '../implementations/types.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const rpcRouteUsers: AnyHttpRouteDoc = {
+  kind: 'rpc',
+  name: 'GetUser',
+  path: '/users/1',
+  method: 'post',
+  scope: 'users',
+  version: 1,
+  jsonSchema: {},
+}
+
+const rpcRouteAdmin: AnyHttpRouteDoc = {
+  kind: 'rpc',
+  name: 'DeleteUser',
+  path: '/admin-users/1',
+  method: 'post',
+  scope: ['admin', 'users'],
+  version: 1,
+  jsonSchema: {},
+}
+
+const rpcRouteUsers2: AnyHttpRouteDoc = {
+  kind: 'rpc',
+  name: 'ListUsers',
+  path: '/users/1',
+  method: 'post',
+  scope: 'users',
+  version: 1,
+  jsonSchema: {},
+}
+
+const apiRouteNoScope: AnyHttpRouteDoc = {
+  kind: 'api',
+  name: 'HealthCheck',
+  path: '/health',
+  method: 'get',
+  fullPath: '/api/health',
+  jsonSchema: {},
+}
+
+const apiRouteWithScope: AnyHttpRouteDoc = {
+  kind: 'api',
+  name: 'ListPosts',
+  path: '/posts',
+  method: 'get',
+  fullPath: '/api/posts',
+  scope: 'posts',
+  jsonSchema: {},
+}
+
+// ---------------------------------------------------------------------------
+// normalizeScope
+// ---------------------------------------------------------------------------
+
+describe('normalizeScope', () => {
+  it('returns a string scope as-is', () => {
+    expect(normalizeScope('users')).toBe('users')
+  })
+
+  it('joins a string array scope with hyphens', () => {
+    expect(normalizeScope(['admin', 'users'])).toBe('admin-users')
+  })
+
+  it('returns "default" for undefined scope', () => {
+    expect(normalizeScope(undefined)).toBe('default')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// scopeToCamelCase
+// ---------------------------------------------------------------------------
+
+describe('scopeToCamelCase', () => {
+  it('returns a single word as-is', () => {
+    expect(scopeToCamelCase('users')).toBe('users')
+  })
+
+  it('converts a hyphenated scope to camelCase', () => {
+    expect(scopeToCamelCase('admin-users')).toBe('adminUsers')
+  })
+
+  it('converts multi-segment hyphenated scope', () => {
+    expect(scopeToCamelCase('super-admin-users')).toBe('superAdminUsers')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// groupRoutesByScope
+// ---------------------------------------------------------------------------
+
+describe('groupRoutesByScope', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('groups routes by their scope', () => {
+    const routes: AnyHttpRouteDoc[] = [rpcRouteUsers, rpcRouteUsers2]
+    const groups = groupRoutesByScope(routes)
+
+    expect(groups.size).toBe(1)
+    expect(groups.has('users')).toBe(true)
+
+    const usersGroup = groups.get('users')!
+    expect(usersGroup.scopeKey).toBe('users')
+    expect(usersGroup.camelCase).toBe('users')
+    expect(usersGroup.routes).toHaveLength(2)
+  })
+
+  it('handles array scopes by joining with hyphens', () => {
+    const routes: AnyHttpRouteDoc[] = [rpcRouteAdmin]
+    const groups = groupRoutesByScope(routes)
+
+    expect(groups.has('admin-users')).toBe(true)
+    const group = groups.get('admin-users')!
+    expect(group.scopeKey).toBe('admin-users')
+    expect(group.camelCase).toBe('adminUsers')
+    expect(group.routes).toHaveLength(1)
+  })
+
+  it('groups routes from multiple scopes', () => {
+    const routes: AnyHttpRouteDoc[] = [rpcRouteUsers, rpcRouteAdmin, apiRouteWithScope]
+    const groups = groupRoutesByScope(routes)
+
+    expect(groups.size).toBe(3)
+    expect(groups.has('users')).toBe(true)
+    expect(groups.has('admin-users')).toBe(true)
+    expect(groups.has('posts')).toBe(true)
+  })
+
+  it('warns on missing scope and groups into "default"', () => {
+    const routes: AnyHttpRouteDoc[] = [apiRouteNoScope]
+    const groups = groupRoutesByScope(routes)
+
+    expect(console.warn).toHaveBeenCalled()
+    expect(groups.has('default')).toBe(true)
+
+    const defaultGroup = groups.get('default')!
+    expect(defaultGroup.scopeKey).toBe('default')
+    expect(defaultGroup.camelCase).toBe('default')
+    expect(defaultGroup.routes).toHaveLength(1)
+  })
+
+  it('does not warn when all routes have scopes', () => {
+    const routes: AnyHttpRouteDoc[] = [rpcRouteUsers, apiRouteWithScope]
+    groupRoutesByScope(routes)
+    expect(console.warn).not.toHaveBeenCalled()
+  })
+})

package/src/codegen/group-routes.ts

@@ -0,0 +1,61 @@
+import type { AnyHttpRouteDoc } from '../implementations/types.js'
+
+export interface ScopeGroup {
+  scopeKey: string
+  camelCase: string
+  routes: AnyHttpRouteDoc[]
+}
+
+/**
+ * Normalizes a scope value to a string key:
+ * - string   → returned as-is
+ * - string[] → joined with '-'
+ * - undefined → 'default'
+ */
+export function normalizeScope(scope: string | string[] | undefined): string {
+  if (scope === undefined) return 'default'
+  if (Array.isArray(scope)) return scope.join('-')
+  return scope
+}
+
+/**
+ * Converts a hyphenated scope key to camelCase.
+ * e.g. 'admin-users' → 'adminUsers', 'users' → 'users'
+ */
+export function scopeToCamelCase(scope: string): string {
+  const parts = scope.split('-')
+  return parts
+    .map((part, index) =>
+      index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+    )
+    .join('')
+}
+
+/**
+ * Groups an array of route docs into a Map keyed by normalized scope.
+ * Routes without a scope emit a console.warn and are grouped under 'default'.
+ */
+export function groupRoutesByScope(routes: AnyHttpRouteDoc[]): Map<string, ScopeGroup> {
+  const groups = new Map<string, ScopeGroup>()
+
+  for (const route of routes) {
+    const rawScope = 'scope' in route ? (route as { scope?: string | string[] }).scope : undefined
+    if (rawScope === undefined) {
+      console.warn(
+        `[ts-procedures] Route "${route.name}" has no scope — it will be grouped under "default".`
+      )
+    }
+
+    const scopeKey = normalizeScope(rawScope)
+    const camelCase = scopeToCamelCase(scopeKey)
+
+    let group = groups.get(scopeKey)
+    if (group === undefined) {
+      group = { scopeKey, camelCase, routes: [] }
+      groups.set(scopeKey, group)
+    }
+    group.routes.push(route)
+  }
+
+  return groups
+}

package/src/codegen/index.ts

@@ -0,0 +1,30 @@
+import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
+import { runPipeline, type GeneratedFile } from './pipeline.js'
+import type { AjscOptions } from './emit-types.js'
+
+export interface GenerateClientOptions extends ResolveInput {
+  outDir: string
+  ajsc?: AjscOptions
+  clientImportPath?: string
+  dryRun?: boolean
+  namespaceTypes?: boolean
+  selfContained?: boolean
+  serviceName?: string
+}
+
+export async function generateClient(options: GenerateClientOptions): Promise<GeneratedFile[]> {
+  const envelope = await resolveEnvelope(options)
+  return runPipeline({
+    envelope,
+    outDir: options.outDir,
+    ajsc: options.ajsc,
+    clientImportPath: options.clientImportPath,
+    dryRun: options.dryRun,
+    namespaceTypes: options.namespaceTypes,
+    selfContained: options.selfContained,
+    serviceName: options.serviceName,
+  })
+}
+
+export type { AjscOptions } from './emit-types.js'
+export type { ResolveInput } from './resolve-envelope.js'

package/src/codegen/naming.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { toPascalCase, validateServiceName } from './naming.js'
+
+describe('toPascalCase', () => {
+  it('converts a single word', () => {
+    expect(toPascalCase('auth')).toBe('Auth')
+  })
+
+  it('converts hyphen-separated words', () => {
+    expect(toPascalCase('auth-service')).toBe('AuthService')
+  })
+
+  it('converts underscore-separated words', () => {
+    expect(toPascalCase('users_api')).toBe('UsersApi')
+  })
+
+  it('converts space-separated words', () => {
+    expect(toPascalCase('my service')).toBe('MyService')
+  })
+
+  it('preserves already-PascalCased input', () => {
+    expect(toPascalCase('UsersApi')).toBe('UsersApi')
+  })
+})
+
+describe('validateServiceName', () => {
+  it('accepts a valid PascalCase name', () => {
+    expect(() => validateServiceName('Auth')).not.toThrow()
+  })
+
+  it('accepts a hyphen-separated name', () => {
+    expect(() => validateServiceName('auth-service')).not.toThrow()
+  })
+
+  it('accepts an underscore-separated name', () => {
+    expect(() => validateServiceName('users_api')).not.toThrow()
+  })
+
+  it('throws for an empty string', () => {
+    expect(() => validateServiceName('')).toThrow('empty')
+  })
+
+  it('throws for a string of only separators', () => {
+    expect(() => validateServiceName('---')).toThrow('empty')
+  })
+
+  it('throws when the result starts with a digit', () => {
+    expect(() => validateServiceName('123service')).toThrow('starts with a digit')
+  })
+})

package/src/codegen/naming.ts

@@ -0,0 +1,25 @@
+/** Converts a string to PascalCase (splits on whitespace, hyphens, underscores). */
+export function toPascalCase(str: string): string {
+  return str
+    .split(/[\s\-_]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('')
+}
+
+/**
+ * Validates that a serviceName option is usable as a TypeScript identifier fragment.
+ * Throws a descriptive error if invalid.
+ */
+export function validateServiceName(serviceName: string): void {
+  const pascal = toPascalCase(serviceName)
+  if (pascal.length === 0) {
+    throw new Error(
+      `[ts-procedures-codegen] --service-name value "${serviceName}" is empty or contains only separator characters.`
+    )
+  }
+  if (/^\d/.test(pascal)) {
+    throw new Error(
+      `[ts-procedures-codegen] --service-name value "${serviceName}" produces "${pascal}" which starts with a digit — provide a name that starts with a letter.`
+    )
+  }
+}