@prisma-next/family-sql 0.5.0-dev.9 → 0.5.1

package/src/core/migrations/types.ts

@@ -1,10 +1,10 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
+  ContractSpace,
   ControlAdapterDescriptor,
   ControlDriverInstance,
   ControlExtensionDescriptor,
-  DataTransformOperation,
   MigratableTargetDescriptor,
   MigrationOperationPolicy,
   MigrationPlan,
@@ -16,47 +16,22 @@ import type {
   MigrationRunnerFailure,
   MigrationRunnerSuccessValue,
   OperationContext,
+  OpFactoryCall,
   SchemaIssue,
 } from '@prisma-next/framework-components/control';
-import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
-import type { SqlOperationDescriptor } from '@prisma-next/sql-operations';
+import type {
+  SqlStorage,
+  StorageColumn,
+  StorageTable,
+  StorageTypeInstance,
+} from '@prisma-next/sql-contract/types';
+import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
 import type { Result } from '@prisma-next/utils/result';
 import type { SqlControlFamilyInstance } from '../control-instance';
 
 export type AnyRecord = Readonly<Record<string, unknown>>;
 
-export interface ComponentDatabaseDependency<TTargetDetails> {
-  readonly id: string;
-  readonly label: string;
-  readonly install: readonly SqlMigrationPlanOperation<TTargetDetails>[];
-}
-
-export interface ComponentDatabaseDependencies<TTargetDetails> {
-  readonly init?: readonly ComponentDatabaseDependency<TTargetDetails>[];
-}
-
-export interface DatabaseDependencyProvider {
-  readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
-}
-
-export function isDatabaseDependencyProvider(value: unknown): value is DatabaseDependencyProvider {
-  return typeof value === 'object' && value !== null && 'databaseDependencies' in value;
-}
-
-export function collectInitDependencies(
-  components: ReadonlyArray<unknown>,
-): readonly ComponentDatabaseDependency<unknown>[] {
-  const result: ComponentDatabaseDependency<unknown>[] = [];
-  for (const component of components) {
-    if (!isDatabaseDependencyProvider(component)) continue;
-    const deps = component.databaseDependencies?.init;
-    if (!deps) continue;
-    result.push(...deps);
-  }
-  return result;
-}
-
 export interface StorageTypePlanResult<TTargetDetails> {
   readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
 }
@@ -83,6 +58,43 @@ export interface ResolveIdentityValueInput {
   readonly typeParams?: Record<string, unknown>;
 }
 
+/**
+ * Per-field lifecycle event a codec hook can react to.
+ *
+ * Fired during app-space migration emission as the SQL family diffs the
+ * prior contract against the new contract. See
+ * `docs/architecture docs/adrs/ADR 213 - Codec lifecycle hooks.md`
+ * for the wiring contract.
+ *
+ * - `'added'`     — the field is present in the new contract but not the prior.
+ * - `'dropped'`   — the field is present in the prior contract but not the new.
+ * - `'altered'`   — the field is present in both and any property other than
+ *                   `codecId` differs. Codec-id changes are a v1 non-goal:
+ *                   when only `codecId` differs, no `'altered'` event fires.
+ */
+export type FieldEvent = 'added' | 'dropped' | 'altered';
+
+/**
+ * Context passed to {@link CodecControlHooks.onFieldEvent}.
+ *
+ * `tableName` and `fieldName` are always populated; `priorTable` /
+ * `priorField` carry the prior contract's view of the table and column
+ * (present for `'dropped'` and `'altered'`); `newTable` / `newField`
+ * carry the new contract's view (present for `'added'` and `'altered'`).
+ *
+ * The hook only ever receives app-space contract IR — extension-space
+ * fields are scoped out by the API: the hook is wired at the
+ * application emitter only.
+ */
+export interface FieldEventContext {
+  readonly tableName: string;
+  readonly fieldName: string;
+  readonly priorTable?: StorageTable;
+  readonly newTable?: StorageTable;
+  readonly priorField?: StorageColumn;
+  readonly newField?: StorageColumn;
+}
+
 export interface CodecControlHooks<TTargetDetails = unknown> {
   planTypeOperations?: (options: {
     readonly typeName: string;
@@ -123,22 +135,57 @@ export interface CodecControlHooks<TTargetDetails = unknown> {
    * - undefined: no opinion; planner may use built-in fallbacks
    */
   resolveIdentityValue?: (input: ResolveIdentityValueInput) => string | null | undefined;
+  /**
+   * Reacts to per-field added / dropped / altered events as the app-space
+   * emitter diffs the prior contract against the new contract. Returned
+   * ops are inlined into the app-space migration's `ops.json` alongside
+   * the user's structural ops.
+   *
+   * Synchronous. Each returned op must carry its own `invariantId`. Hooks
+   * are dispatched per `(table, field)` based on the field's `codecId`
+   * (the new field's codec for `'added'` / `'altered'`; the prior field's
+   * codec for `'dropped'`).
+   *
+   * See `docs/architecture docs/adrs/ADR 213 - Codec lifecycle hooks.md`
+   * for the wiring contract and the deterministic ordering rule.
+   */
+  onFieldEvent?: (event: FieldEvent, ctx: FieldEventContext) => readonly OpFactoryCall[];
 }
 
 export interface SqlControlExtensionDescriptor<TTargetId extends string>
   extends ControlExtensionDescriptor<'sql', TTargetId> {
-  readonly databaseDependencies?: ComponentDatabaseDependencies<unknown>;
-  readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
+  readonly queryOperations?: () => SqlOperationDescriptors;
+  /**
+   * Schema-contributing extensions opt into the per-space planner / runner /
+   * verifier by setting this field. Extensions without it are codec-only or
+   * query-ops-only — today's behaviour preserved.
+   *
+   * The shape comes from `@prisma-next/framework-components/control`
+   * (`ContractSpace`) — contract-space identity is a framework concept,
+   * not a SQL-specific one. The SQL family specialises the generic to
+   * `Contract<SqlStorage>` so descriptor authors continue to see a
+   * typed contract value.
+   */
+  readonly contractSpace?: ContractSpace<Contract<SqlStorage>>;
 }
 
 export interface SqlControlAdapterDescriptor<TTargetId extends string>
   extends ControlAdapterDescriptor<'sql', TTargetId> {
-  readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
+  readonly queryOperations?: () => SqlOperationDescriptors;
 }
 
 export interface SqlMigrationPlanOperationStep {
   readonly description: string;
   readonly sql: string;
+  /**
+   * Optional parameter values bound at execution time. The runner forwards
+   * these to `driver.query(sql, params ?? [])`, so step authors can use
+   * placeholder syntax (`$1`, `$2`, …) instead of inlining literals into
+   * the SQL string. Reuses the driver's parameter binder rather than
+   * rolling per-target literal serialization for every type the planner
+   * may emit.
+   */
+  readonly params?: readonly unknown[];
   readonly meta?: AnyRecord;
 }
 
@@ -168,25 +215,27 @@ export interface SqlMigrationPlanOperation<TTargetDetails> extends MigrationPlan
   readonly meta?: AnyRecord;
 }
 
-/**
- * Union of all operation shapes a SQL-family migration may emit: schema-facing
- * `SqlMigrationPlanOperation`s and family-agnostic `DataTransformOperation`s.
- *
- * Mirrors `AnyMongoMigrationOperation` in shape — the runner already handles
- * both branches via `isDataTransformOperation`, and authored `migration.ts`
- * files must be able to intermix `dataTransform(endContract, …)` calls with
- * DDL factory calls (e.g. `setNotNull(…)`) in a single `operations` array.
- */
-export type AnySqlMigrationOperation<TTargetDetails> =
-  | SqlMigrationPlanOperation<TTargetDetails>
-  | DataTransformOperation;
-
 export interface SqlMigrationPlanContractInfo {
   readonly storageHash: string;
   readonly profileHash?: string;
 }
 
 export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
+  /**
+   * Contract space this plan applies to. The runner uses this to key the
+   * `prisma_contract.marker` row it writes/reads (`space = <spaceId>`),
+   * so per-extension plans hit per-extension marker rows instead of all
+   * collapsing onto the app's row.
+   *
+   * App-plan callers pass `APP_SPACE_ID` (`'app'`); per-extension plans
+   * pass the extension's space id. Required at every call site so the
+   * type system surfaces every place that needs to thread the value
+   * (rather than letting an `?? APP_SPACE_ID` fall-through silently
+   * collapse multi-space markers onto the `'app'` row).
+   *
+   * @see specs/framework-mechanism.spec.md § 2.
+   */
+  readonly spaceId: string;
   /**
    * Origin contract identity that the plan expects the database to currently be at.
    * If omitted or null, the runner skips origin validation entirely.
@@ -197,6 +246,15 @@ export interface SqlMigrationPlan<TTargetDetails> extends MigrationPlan {
    */
   readonly destination: SqlMigrationPlanContractInfo;
   readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  /**
+   * Sorted, deduplicated invariant ids declared by this plan's data-transform
+   * ops. Required at the SQL-family layer (the SQL runners consume this as
+   * the source of truth for marker writes and self-edge no-op checks); the
+   * framework-level {@link MigrationPlan.providedInvariants} stays optional
+   * because `db init` / `db update` plans don't have a corresponding
+   * migration manifest.
+   */
+  readonly providedInvariants: readonly string[];
   readonly meta?: AnyRecord;
 }
 
@@ -243,17 +301,33 @@ export interface SqlMigrationPlannerPlanOptions {
   readonly policy: MigrationOperationPolicy;
   readonly schemaName?: string;
   /**
-   * The "from" contract (state the planner assumes the database starts at).
-   * Only `migration plan` supplies this; `db update` / `db init` reconcile
-   * against the live schema with no old contract. Strategies that need
-   * from/to column-shape comparisons (unsafe type change, nullability
+   * Contract space the plan applies to. The planner stamps this onto
+   * the produced {@link SqlMigrationPlan.spaceId} so the runner keys
+   * the marker row by the right space. App-plan callers pass
+   * `APP_SPACE_ID`; per-extension callers pass the extension's space
+   * id.
+   */
+  readonly spaceId: string;
+  /**
+   * The "from" contract (state the planner assumes the database starts at),
+   * or `null` for reconciliation flows that have no prior contract.
+   *
+   * Required at every call site so the structural fact "I have a prior
+   * contract / I don't" is visible in the type. `migration plan` supplies
+   * the previous bundle's `metadata.toContract`; `db update` / `db init`
+   * reconcile against the live schema and pass `null`. Strategies that
+   * need from/to column-shape comparisons (unsafe type change, nullability
    * tightening) use this to decide whether to emit `dataTransform`
-   * placeholders.
+   * placeholders; they short-circuit when it is `null`.
+   *
+   * Planners also derive the "from" identity they stamp onto the produced
+   * plan's `describe()` as `fromContract?.storage.storageHash ?? null`.
    */
-  readonly fromContract?: Contract<SqlStorage> | null;
+  readonly fromContract: Contract<SqlStorage> | null;
   /**
    * Active framework components participating in this composition.
-   * SQL targets can interpret this list to derive database dependencies.
+   * Each component is target-bound so SQL targets can dispatch
+   * component-owned planning behaviour from the same descriptor list.
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
@@ -271,6 +345,14 @@ export interface SqlMigrationRunnerExecuteCallbacks<TTargetDetails> {
 export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly plan: SqlMigrationPlan<TTargetDetails>;
   readonly driver: ControlDriverInstance<'sql', string>;
+  /**
+   * Logical contract space this plan applies to. When omitted the
+   * runner derives the space from {@link SqlMigrationPlan.spaceId};
+   * when supplied, the runner asserts it matches `plan.spaceId` so a
+   * caller cannot accidentally write the marker row for a different
+   * space than the plan was produced for.
+   */
+  readonly space?: string;
   /**
    * Destination contract IR.
    * Must correspond to `plan.destination` and is used for schema verification and marker/ledger writes.
@@ -292,7 +374,8 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
   readonly executionChecks?: MigrationRunnerExecutionChecks;
   /**
    * Active framework components participating in this composition.
-   * SQL targets can interpret this list to derive database dependencies.
+   * Each component is target-bound so SQL targets can dispatch
+   * component-owned execution behaviour from the same descriptor list.
    * All components must have matching familyId ('sql') and targetId.
    */
   readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
@@ -300,11 +383,13 @@ export interface SqlMigrationRunnerExecuteOptions<TTargetDetails> {
 
 export type SqlMigrationRunnerErrorCode =
   | 'DESTINATION_CONTRACT_MISMATCH'
+  | 'LEGACY_MARKER_SHAPE'
   | 'MARKER_ORIGIN_MISMATCH'
   | 'POLICY_VIOLATION'
   | 'PRECHECK_FAILED'
   | 'POSTCHECK_FAILED'
   | 'SCHEMA_VERIFY_FAILED'
+  | 'FOREIGN_KEY_VIOLATION'
   | 'EXECUTION_FAILED';
 
 export interface SqlMigrationRunnerFailure extends MigrationRunnerFailure {
@@ -320,22 +405,85 @@ export type SqlMigrationRunnerResult = Result<
 >;
 
 export interface SqlMigrationRunner<TTargetDetails> {
+  /**
+   * Apply a single migration plan, opening and managing its own
+   * transaction (and any target-specific connection-level setup, e.g.
+   * SQLite's `PRAGMA foreign_keys` toggle). Existing single-space
+   * callers route through here.
+   */
   execute(
     options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
   ): Promise<SqlMigrationRunnerResult>;
+
+  /**
+   * Apply a single migration plan against an already-open connection
+   * **without** opening a transaction. The caller is responsible for
+   * wrapping the call (and any siblings) in `BEGIN` / `COMMIT` /
+   * `ROLLBACK`. Used by the per-space runner wiring to fan out across
+   * contract spaces inside one outer transaction so a mid-apply
+   * failure rolls back every space's writes.
+   *
+   * Idempotent control-table setup (`prisma_contract.*`) and marker
+   * writes use `options.space` to address the per-space marker row.
+   */
+  executeOnConnection(
+    options: SqlMigrationRunnerExecuteOptions<TTargetDetails>,
+  ): Promise<SqlMigrationRunnerResult>;
+
+  /**
+   * Apply per-space plans across multiple contract spaces inside a
+   * single outer transaction. The caller orders the input list
+   * (typically via the aggregate planner's `applyOrder`: extensions
+   * alphabetical, then app); the runner is responsible for opening
+   * / committing the outer
+   * transaction (and any target-specific connection-level setup such
+   * as the SQLite FK pragma toggle). A failure on any space rolls
+   * back every space's writes.
+   *
+   * Each space's `SqlMigrationRunnerExecuteOptions` must reference the
+   * same `driver` (the connection the outer transaction is open on).
+   * Per-space marker writes use `options.space` to address the row.
+   */
+  executeAcrossSpaces(options: {
+    readonly driver: ControlDriverInstance<'sql', string>;
+    readonly perSpaceOptions: ReadonlyArray<SqlMigrationRunnerExecuteOptions<TTargetDetails>>;
+  }): Promise<MultiSpaceRunnerResult>;
 }
 
+export interface MultiSpaceRunnerSuccessValue {
+  readonly perSpaceResults: ReadonlyArray<{
+    readonly space: string;
+    readonly value: SqlMigrationRunnerSuccessValue;
+  }>;
+}
+
+export interface MultiSpaceRunnerFailure extends SqlMigrationRunnerFailure {
+  readonly failingSpace: string;
+}
+
+export type MultiSpaceRunnerResult = Result<MultiSpaceRunnerSuccessValue, MultiSpaceRunnerFailure>;
+
 export interface SqlControlTargetDescriptor<TTargetId extends string, TTargetDetails>
   extends MigratableTargetDescriptor<'sql', TTargetId, SqlControlFamilyInstance> {
-  readonly queryOperations?: () => ReadonlyArray<SqlOperationDescriptor>;
+  readonly queryOperations?: () => SqlOperationDescriptors;
   createPlanner(family: SqlControlFamilyInstance): SqlMigrationPlanner<TTargetDetails>;
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }
 
 export interface CreateSqlMigrationPlanOptions<TTargetDetails> {
   readonly targetId: string;
+  /**
+   * Contract space this plan applies to. Mirrors {@link SqlMigrationPlan.spaceId}.
+   */
+  readonly spaceId: string;
   readonly origin?: SqlMigrationPlanContractInfo | null;
   readonly destination: SqlMigrationPlanContractInfo;
   readonly operations: readonly SqlMigrationPlanOperation<TTargetDetails>[];
+  /**
+   * Sorted, deduplicated invariant ids for this plan; mirrors the required
+   * field on {@link SqlMigrationPlan}. Callers without a migration manifest
+   * (`db init`, `db update`, planner-built plans) pass `[]`.
+   */
+  readonly providedInvariants: readonly string[];
   readonly meta?: AnyRecord;
 }

package/src/core/operation-preview.ts

@@ -0,0 +1,62 @@
+import type {
+  MigrationPlanOperation,
+  OperationPreview,
+} from '@prisma-next/framework-components/control';
+
+/**
+ * Shape of an SQL execute step on `SqlMigrationPlanOperation`. Used for runtime
+ * type narrowing without importing the concrete SQL type.
+ */
+interface SqlExecuteStep {
+  readonly sql: string;
+}
+
+function isDdlStatement(sqlStatement: string): boolean {
+  const trimmed = sqlStatement.trim().toLowerCase();
+  return (
+    trimmed.startsWith('create ') || trimmed.startsWith('alter ') || trimmed.startsWith('drop ')
+  );
+}
+
+function hasExecuteSteps(
+  operation: MigrationPlanOperation,
+): operation is MigrationPlanOperation & { readonly execute: readonly SqlExecuteStep[] } {
+  const candidate = operation as unknown as Record<string, unknown>;
+  if (!('execute' in candidate) || !Array.isArray(candidate['execute'])) {
+    return false;
+  }
+  return candidate['execute'].every(
+    (step: unknown) => typeof step === 'object' && step !== null && 'sql' in step,
+  );
+}
+
+/**
+ * Extracts a best-effort SQL DDL preview for CLI plan output.
+ * Presentation-only: never used to decide migration correctness.
+ */
+export function extractSqlDdl(operations: readonly MigrationPlanOperation[]): string[] {
+  const statements: string[] = [];
+  for (const operation of operations) {
+    if (!hasExecuteSteps(operation)) {
+      continue;
+    }
+    for (const step of operation.execute) {
+      if (typeof step.sql === 'string' && isDdlStatement(step.sql)) {
+        statements.push(step.sql.trim());
+      }
+    }
+  }
+  return statements;
+}
+
+/**
+ * Wraps `extractSqlDdl` into the family-agnostic `OperationPreview` shape.
+ * Each statement carries `language: 'sql'`.
+ */
+export function sqlOperationsToPreview(
+  operations: readonly MigrationPlanOperation[],
+): OperationPreview {
+  return {
+    statements: extractSqlDdl(operations).map((text) => ({ text, language: 'sql' })),
+  };
+}

package/src/core/psl-contract-infer/default-mapping.ts

@@ -0,0 +1,56 @@
+import type { ColumnDefault } from '@prisma-next/contract/types';
+
+const DEFAULT_FUNCTION_ATTRIBUTES: Readonly<Record<string, string>> = {
+  'autoincrement()': '@default(autoincrement())',
+  'now()': '@default(now())',
+};
+
+export interface DefaultMappingOptions {
+  readonly functionAttributes?: Readonly<Record<string, string>>;
+  readonly fallbackFunctionAttribute?: ((expression: string) => string | undefined) | undefined;
+}
+
+export type DefaultMappingResult = { readonly attribute: string } | { readonly comment: string };
+
+export function mapDefault(
+  columnDefault: ColumnDefault,
+  options?: DefaultMappingOptions,
+): DefaultMappingResult {
+  switch (columnDefault.kind) {
+    case 'literal':
+      return { attribute: `@default(${formatLiteralValue(columnDefault.value)})` };
+    case 'function': {
+      const attribute =
+        options?.functionAttributes?.[columnDefault.expression] ??
+        DEFAULT_FUNCTION_ATTRIBUTES[columnDefault.expression] ??
+        options?.fallbackFunctionAttribute?.(columnDefault.expression);
+      return attribute
+        ? { attribute }
+        : { comment: `// Raw default: ${columnDefault.expression.replace(/[\r\n]+/g, ' ')}` };
+    }
+  }
+}
+
+function formatLiteralValue(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  switch (typeof value) {
+    case 'boolean':
+    case 'number':
+      return String(value);
+    case 'string':
+      return quoteString(value);
+    default:
+      return quoteString(JSON.stringify(value));
+  }
+}
+
+function quoteString(str: string): string {
+  return `"${escapeString(str)}"`;
+}
+
+function escapeString(str: string): string {
+  return JSON.stringify(str).slice(1, -1);
+}

package/src/core/psl-contract-infer/name-transforms.ts

@@ -0,0 +1,178 @@
+const PSL_RESERVED_WORDS = new Set(['model', 'enum', 'types', 'type', 'generator', 'datasource']);
+
+const IDENTIFIER_PART_PATTERN = /[A-Za-z0-9]+/g;
+
+type NameResult = {
+  readonly name: string;
+  readonly map?: string;
+};
+
+function hasSeparators(input: string): boolean {
+  return /[^A-Za-z0-9]/.test(input);
+}
+
+function extractIdentifierParts(input: string): string[] {
+  return input.match(IDENTIFIER_PART_PATTERN) ?? [];
+}
+
+function createSyntheticIdentifier(input: string): string {
+  let hash = 2166136261;
+
+  for (const char of input) {
+    hash ^= char.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+
+  return `x${(hash >>> 0).toString(16)}`;
+}
+
+function sanitizeIdentifierCharacters(input: string): string {
+  const sanitized = input.replace(/[^\w]/g, '');
+  return sanitized.length > 0 ? sanitized : createSyntheticIdentifier(input);
+}
+
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function snakeToPascalCase(input: string): string {
+  const parts = extractIdentifierParts(input);
+  if (parts.length === 0) {
+    return capitalize(sanitizeIdentifierCharacters(input));
+  }
+  return parts.map(capitalize).join('');
+}
+
+function snakeToCamelCase(input: string): string {
+  const parts = extractIdentifierParts(input);
+  if (parts.length === 0) {
+    return sanitizeIdentifierCharacters(input);
+  }
+  const [firstPart = input, ...rest] = parts;
+  return firstPart.charAt(0).toLowerCase() + firstPart.slice(1) + rest.map(capitalize).join('');
+}
+
+function needsEscaping(name: string): boolean {
+  return PSL_RESERVED_WORDS.has(name.toLowerCase()) || /^\d/.test(name);
+}
+
+function escapeName(name: string): string {
+  return `_${name}`;
+}
+
+function escapeIfNeeded(name: string): string {
+  return needsEscaping(name) ? escapeName(name) : name;
+}
+
+export function toModelName(tableName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(tableName)) {
+    name = snakeToPascalCase(tableName);
+  } else {
+    name = tableName.charAt(0).toUpperCase() + tableName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: tableName };
+  }
+
+  if (name !== tableName) {
+    return { name, map: tableName };
+  }
+
+  return { name };
+}
+
+export function toFieldName(columnName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(columnName)) {
+    name = snakeToCamelCase(columnName);
+  } else {
+    name = columnName.charAt(0).toLowerCase() + columnName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: columnName };
+  }
+
+  if (name !== columnName) {
+    return { name, map: columnName };
+  }
+
+  return { name };
+}
+
+export function toEnumName(pgTypeName: string): NameResult {
+  let name: string;
+
+  if (hasSeparators(pgTypeName)) {
+    name = snakeToPascalCase(pgTypeName);
+  } else {
+    name = pgTypeName.charAt(0).toUpperCase() + pgTypeName.slice(1);
+  }
+
+  if (needsEscaping(name)) {
+    const escaped = escapeName(name);
+    return { name: escaped, map: pgTypeName };
+  }
+
+  if (name !== pgTypeName) {
+    return { name, map: pgTypeName };
+  }
+
+  return { name };
+}
+
+export function pluralize(word: string): string {
+  if (
+    word.endsWith('s') ||
+    word.endsWith('x') ||
+    word.endsWith('z') ||
+    word.endsWith('ch') ||
+    word.endsWith('sh')
+  ) {
+    return `${word}es`;
+  }
+  if (word.endsWith('y') && !/[aeiou]y$/i.test(word)) {
+    return `${word.slice(0, -1)}ies`;
+  }
+  return `${word}s`;
+}
+
+export function deriveRelationFieldName(
+  fkColumns: readonly string[],
+  referencedTableName: string,
+): string {
+  if (fkColumns.length === 1) {
+    const [col = referencedTableName] = fkColumns;
+    const stripped = col.replace(/_id$/i, '').replace(/Id$/, '');
+
+    if (stripped.length > 0 && stripped !== col) {
+      return escapeIfNeeded(snakeToCamelCase(stripped));
+    }
+    return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+  }
+
+  return escapeIfNeeded(snakeToCamelCase(referencedTableName));
+}
+
+export function deriveBackRelationFieldName(childModelName: string, isOneToOne: boolean): string {
+  const base = childModelName.charAt(0).toLowerCase() + childModelName.slice(1);
+  return isOneToOne ? base : pluralize(base);
+}
+
+export function toNamedTypeName(columnName: string): string {
+  let name: string;
+
+  if (hasSeparators(columnName)) {
+    name = snakeToPascalCase(columnName);
+  } else {
+    name = columnName.charAt(0).toUpperCase() + columnName.slice(1);
+  }
+
+  return escapeIfNeeded(name);
+}