@owlmeans/postgres-resource 0.1.18-rc.42 → 0.1.18-rc.43

package/build/utils/schema.js

@@ -1,382 +1,369 @@
 import { UnsupportedArgumentError } from '@owlmeans/resource';
 import { logger } from '@owlmeans/log';
 import { DEF_ID_DEFAULT, DEF_JSON_TYPE, DEF_SQL_TYPE, ID_FIELD, PG_KEYWORD, PgIndexMethod } from '../consts.js';
-import { pgIdentifier, qualify, quoteIdent } from './name.js';
+import { pgNameHelper } from './name.js';
+import { INT32_MAX } from './consts.local.js';
 const log = logger('postgres-resource');
-const INT32_MAX = 2147483647;
-/**
- * Normalize a Postgres type name to the spelling `format_type()` reports, so the drift
- * comparison against a live table is an exact string match instead of a fuzzy one.
- */
-export const toFormatType = (type) => {
-    const trimmed = type.trim().toLowerCase();
-    const match = /^([a-z0-9_ ]+?)\s*(\(([^)]*)\))?\s*(\[\])?$/.exec(trimmed);
-    if (match == null) {
-        return trimmed;
-    }
-    const [, base, , args, array] = match;
-    const aliases = {
-        int: 'integer', int4: 'integer', int2: 'smallint', int8: 'bigint', serial: 'integer',
-        bool: 'boolean', float4: 'real', float8: 'double precision', decimal: 'numeric',
-        varchar: 'character varying', char: 'character', bpchar: 'character',
-        timestamptz: 'timestamp with time zone', timetz: 'time with time zone',
-        timestamp: 'timestamp without time zone', time: 'time without time zone'
-    };
-    const resolved = aliases[base.trim()] ?? base.trim();
-    /** Postgres prints multi-argument typmods without spaces: `numeric(12,2)`. */
-    const suffix = args != null ? `(${args.split(',').map(part => part.trim()).join(',')})` : '';
-    return `${resolved}${suffix}${array ?? ''}`;
-};
-const readOverride = (property) => property[PG_KEYWORD] ?? {};
-/**
- * Nullability is decided in exactly one place and threaded down from there. Mongo's mapper
- * recomputes it per branch and lost it twice — on `date-time` and on optional objects.
- */
-const isNullable = (property, isRequired) => {
-    const override = readOverride(property);
-    if (override.nullable != null) {
-        return override.nullable;
-    }
-    if (property.nullable === true) {
-        return true;
-    }
-    if (Array.isArray(property.type) && property.type.includes('null')) {
-        return true;
-    }
-    return !isRequired;
-};
-const baseType = (property) => Array.isArray(property.type) ? property.type.find(type => type !== 'null') : property.type;
-const scalarSqlType = (property) => {
-    const override = readOverride(property);
-    const type = baseType(property);
-    switch (type) {
-        case 'string':
-            switch (property.format) {
-                case 'date-time': return { sqlType: 'timestamp with time zone', jsonType: 'date' };
-                case 'date': return { sqlType: 'date', jsonType: 'date' };
-                case 'time': return { sqlType: 'time without time zone', jsonType: 'string' };
-                case 'uuid': return { sqlType: 'uuid', jsonType: 'string' };
-                case 'binary': return { sqlType: 'bytea', jsonType: 'binary' };
-                default: break;
-            }
-            return property.maxLength != null
-                ? { sqlType: `character varying(${property.maxLength})`, jsonType: 'string' }
-                : { sqlType: DEF_SQL_TYPE, jsonType: 'string' };
-        case 'integer':
-            return property.maximum != null && property.maximum > INT32_MAX
-                ? { sqlType: 'bigint', jsonType: 'bigint' }
-                : { sqlType: 'integer', jsonType: 'integer' };
-        case 'number':
-            return override.precision != null
-                ? { sqlType: `numeric(${override.precision},${override.scale ?? 0})`, jsonType: 'number' }
-                : { sqlType: 'double precision', jsonType: 'number' };
-        case 'boolean':
-            return { sqlType: 'boolean', jsonType: 'boolean' };
-        case 'object':
-            /**
-             * The framework's date convention — `{ type: 'object', format: 'date-time' }`. Mongo's
-             * mapper broke twice on exactly this branch by dropping nullability, so nullability is
-             * decided by the caller, never here.
-             */
-            return property.format === 'date-time'
-                ? { sqlType: 'timestamp with time zone', jsonType: 'date' }
-                : { sqlType: DEF_JSON_TYPE, jsonType: 'object' };
-        default:
-            return { sqlType: DEF_JSON_TYPE, jsonType: 'unknown' };
-    }
-};
-const arraySqlType = (property) => {
-    const items = property.items;
-    const itemType = items != null ? baseType(items) : undefined;
-    /** Only scalar element types become Postgres arrays; anything else stays jsonb. */
-    if (items != null && itemType != null && ['string', 'integer', 'number', 'boolean'].includes(itemType)
-        && items.format == null && items.enum == null) {
-        const scalar = scalarSqlType(items);
-        return { sqlType: `${scalar.sqlType}[]`, jsonType: 'array', array: true };
-    }
-    return { sqlType: DEF_JSON_TYPE, jsonType: 'array', array: false };
-};
-const compileColumn = (name, property, required) => {
-    const override = readOverride(property);
-    const secure = property.secure === true;
-    const type = baseType(property);
-    const nullable = isNullable(property, required.includes(name));
-    let sqlType;
-    let jsonType;
-    let array = false;
-    if (override.type != null) {
-        sqlType = override.type;
-        jsonType = secure ? 'string' : scalarSqlType(property).jsonType;
-        array = override.array === true || override.type.endsWith('[]');
-    }
-    else if (secure) {
-        /**
-         * A secure field is stored as ciphertext, so its declared JSON type says nothing about
-         * its column. It's always unbounded text: `maxLength` would truncate the ciphertext,
-         * an enum CHECK would never match it, and jsonb would fail to parse it.
-         */
-        sqlType = DEF_SQL_TYPE;
-        jsonType = 'string';
-    }
-    else if (type === 'array') {
-        const resolved = arraySqlType(property);
-        sqlType = resolved.sqlType;
-        jsonType = resolved.jsonType;
-        array = resolved.array;
-    }
-    else {
-        const resolved = scalarSqlType(property);
-        sqlType = resolved.sqlType;
-        jsonType = resolved.jsonType;
-    }
-    if (override.length != null) {
-        sqlType = `character varying(${override.length})`;
-    }
-    if (override.array === true && !array && !sqlType.endsWith('[]')) {
-        sqlType = `${sqlType}[]`;
-        array = true;
-    }
-    if (override.jsonb === true) {
-        sqlType = DEF_JSON_TYPE;
-        jsonType = jsonType === 'array' ? 'array' : 'object';
-        array = false;
-    }
-    const formatted = toFormatType(sqlType);
-    const isJsonb = formatted === 'jsonb' || formatted === 'json';
-    const column = {
-        property: name,
-        /** No implicit snake_casing — a silent rename is a silent DROP plus ADD. */
-        column: pgIdentifier(override.column ?? name),
-        sqlType: formatted,
-        jsonType,
-        notNull: override.nullable === false ? true : !nullable,
-        primaryKey: override.primaryKey === true,
-        secure,
-        jsonb: isJsonb,
-        array,
-        managed: override.managed !== false,
-        ...(override.using != null ? { using: override.using } : {}),
-        ...(override.comment != null ? { comment: override.comment } : {})
+export const createPgSchemaHelper = () => {
+    const { pgIdentifier, qualify, quoteIdent } = pgNameHelper;
+    const toFormatType = (type) => {
+        const trimmed = type.trim().toLowerCase();
+        const match = /^([a-z0-9_ ]+?)\s*(\(([^)]*)\))?\s*(\[\])?$/.exec(trimmed);
+        if (match == null) {
+            return trimmed;
+        }
+        const [, base, , args, array] = match;
+        const aliases = {
+            int: 'integer', int4: 'integer', int2: 'smallint', int8: 'bigint', serial: 'integer',
+            bool: 'boolean', float4: 'real', float8: 'double precision', decimal: 'numeric',
+            varchar: 'character varying', char: 'character', bpchar: 'character',
+            timestamptz: 'timestamp with time zone', timetz: 'time with time zone',
+            timestamp: 'timestamp without time zone', time: 'time without time zone'
+        };
+        const resolved = aliases[base.trim()] ?? base.trim();
+        /** Postgres prints multi-argument typmods without spaces: `numeric(12,2)`. */
+        const suffix = args != null ? `(${args.split(',').map(part => part.trim()).join(',')})` : '';
+        return `${resolved}${suffix}${array ?? ''}`;
     };
-    if (override.defaultRaw != null) {
-        column.defaultRaw = override.defaultRaw;
-    }
-    else if (override.default !== undefined) {
-        column.defaultLiteral = override.default;
-    }
-    else if (property.default !== undefined && !isJsonb && !array) {
-        /** Non-scalar defaults stay in `getDefaults()` only — they'd need casting in DDL. */
-        column.defaultLiteral = property.default;
-    }
-    return column;
-};
-const collectProperties = (schema) => {
-    const properties = { ...schema.properties };
-    const required = [...(schema.required ?? [])];
-    /** `allOf` composition is used across the framework's schemas — flatten it like mongo does. */
-    for (const part of schema.allOf ?? []) {
-        const nested = collectProperties(part);
-        Object.assign(properties, nested.properties);
-        required.push(...nested.required);
-    }
-    return { properties, required };
-};
-/**
- * Collapse specs that resolved to the same object name, first declaration wins.
- *
- * The same index can legitimately be declared twice — a schema-root `pg.indexes` entry, a
- * per-property `pg: { index: ... }` override and a `resource.index()` call all land in one
- * list, and nothing stops a declaration from repeating one of the others. Two entries with
- * one name emit the same `CREATE INDEX` twice inside a single DDL transaction, and Postgres
- * answers the second with `42P07 already exists` — which rolls back the whole plan, so the
- * table the first statement created never lands and the resource can never initialize.
- * Duplicates are a declaration style, not a schema error: dedupe them, don't fail the boot.
- */
-const byName = (specs, alias, kind) => {
-    const seen = new Map();
-    for (const spec of specs) {
-        const name = spec.name;
-        if (seen.has(name)) {
-            log.warn('Duplicate declaration, keeping the first one', { resource: alias, kind, name });
-            continue;
+    const readOverride = (property) => property[PG_KEYWORD] ?? {};
+    /**
+     * Nullability is decided in exactly one place and threaded down from there. Mongo's mapper
+     * recomputes it per branch and lost it twice — on `date-time` and on optional objects.
+     */
+    const isNullable = (property, isRequired) => {
+        const override = readOverride(property);
+        if (override.nullable != null) {
+            return override.nullable;
         }
-        seen.set(name, spec);
-    }
-    return [...seen.values()];
-};
-/**
- * Compile a resource's AJV schema into the table specification that drives both DDL
- * emission and drift detection.
- *
- * `extraIndexes` carries what `resource.index()` declared. It's compiled here rather than
- * merged afterwards so chained declarations get the same property-to-column mapping and
- * the same generated names as schema-borne ones.
- *
- * @throws {UnsupportedArgumentError} when an override asks for something unrepresentable.
- */
-export const schemaToTableSpec = (alias, schema, pgSchema, table, autoSync, extraIndexes = []) => {
-    const raw = (schema ?? {});
-    const root = raw[PG_KEYWORD] ?? {};
-    const { properties, required } = collectProperties(raw);
-    const columns = [];
-    const uniques = [...(root.unique ?? [])];
-    const checks = [...(root.checks ?? [])];
-    const indexes = [...(root.indexes ?? []), ...extraIndexes];
-    const references = [];
-    const resolvedTable = pgIdentifier(root.table ?? table);
-    const resolvedSchema = pgIdentifier(root.schema ?? pgSchema);
-    for (const [name, property] of Object.entries(properties)) {
-        const column = compileColumn(name, property, required);
-        columns.push(column);
+        if (property.nullable === true) {
+            return true;
+        }
+        if (Array.isArray(property.type) && property.type.includes('null')) {
+            return true;
+        }
+        return !isRequired;
+    };
+    const baseType = (property) => Array.isArray(property.type) ? property.type.find(type => type !== 'null') : property.type;
+    const scalarSqlType = (property) => {
         const override = readOverride(property);
-        if (override.unique != null && override.unique !== false) {
-            if (column.secure) {
+        const type = baseType(property);
+        switch (type) {
+            case 'string':
+                switch (property.format) {
+                    case 'date-time': return { sqlType: 'timestamp with time zone', jsonType: 'date' };
+                    case 'date': return { sqlType: 'date', jsonType: 'date' };
+                    case 'time': return { sqlType: 'time without time zone', jsonType: 'string' };
+                    case 'uuid': return { sqlType: 'uuid', jsonType: 'string' };
+                    case 'binary': return { sqlType: 'bytea', jsonType: 'binary' };
+                    default: break;
+                }
+                return property.maxLength != null
+                    ? { sqlType: `character varying(${property.maxLength})`, jsonType: 'string' }
+                    : { sqlType: DEF_SQL_TYPE, jsonType: 'string' };
+            case 'integer':
+                return property.maximum != null && property.maximum > INT32_MAX
+                    ? { sqlType: 'bigint', jsonType: 'bigint' }
+                    : { sqlType: 'integer', jsonType: 'integer' };
+            case 'number':
+                return override.precision != null
+                    ? { sqlType: `numeric(${override.precision},${override.scale ?? 0})`, jsonType: 'number' }
+                    : { sqlType: 'double precision', jsonType: 'number' };
+            case 'boolean':
+                return { sqlType: 'boolean', jsonType: 'boolean' };
+            case 'object':
                 /**
-                 * Encryption uses a managed nonce, so two identical plaintexts encrypt to different
-                 * ciphertexts — a unique constraint on the column would never collide, silently.
+                 * The framework's date convention — `{ type: 'object', format: 'date-time' }`. Mongo's
+                 * mapper broke twice on exactly this branch by dropping nullability, so nullability is
+                 * decided by the caller, never here.
                  */
-                throw new UnsupportedArgumentError(`secure-unique:${name}`);
-            }
-            uniques.push({
-                columns: [name],
-                ...(typeof override.unique === 'string' ? { name: override.unique } : {})
-            });
+                return property.format === 'date-time'
+                    ? { sqlType: 'timestamp with time zone', jsonType: 'date' }
+                    : { sqlType: DEF_JSON_TYPE, jsonType: 'object' };
+            default:
+                return { sqlType: DEF_JSON_TYPE, jsonType: 'unknown' };
         }
-        if (override.index != null && override.index !== false) {
-            if (column.secure) {
-                log.warn('Index on a secure column will never match: encryption is non-deterministic', {
-                    resource: alias, column: name,
-                });
-            }
-            const specs = override.index === true
-                ? [{ columns: [name] }]
-                : Array.isArray(override.index) ? override.index : [override.index];
-            indexes.push(...specs.map(spec => ({ ...spec, columns: spec.columns ?? [name] })));
+    };
+    const arraySqlType = (property) => {
+        const items = property.items;
+        const itemType = items != null ? baseType(items) : undefined;
+        /** Only scalar element types become Postgres arrays; anything else stays jsonb. */
+        if (items != null && itemType != null && ['string', 'integer', 'number', 'boolean'].includes(itemType)
+            && items.format == null && items.enum == null) {
+            const scalar = scalarSqlType(items);
+            return { sqlType: `${scalar.sqlType}[]`, jsonType: 'array', array: true };
         }
-        if (override.references != null) {
-            references.push({
-                ...override.references,
-                property: name,
-                column: override.references.column ?? ID_FIELD,
-                name: pgIdentifier(override.references.name ?? `${resolvedTable}_${column.column}_fkey`)
-            });
+        return { sqlType: DEF_JSON_TYPE, jsonType: 'array', array: false };
+    };
+    const compileColumn = (name, property, required) => {
+        const override = readOverride(property);
+        const secure = property.secure === true;
+        const type = baseType(property);
+        const nullable = isNullable(property, required.includes(name));
+        let sqlType;
+        let jsonType;
+        let array = false;
+        if (override.type != null) {
+            sqlType = override.type;
+            jsonType = secure ? 'string' : scalarSqlType(property).jsonType;
+            array = override.array === true || override.type.endsWith('[]');
         }
-        if (override.check != null) {
-            checks.push({
-                name: `${resolvedTable}_${column.column}_check`,
-                expression: override.check.replace(/\{\{col\}\}/g, quoteIdent(column.column))
-            });
+        else if (secure) {
+            /**
+             * A secure field is stored as ciphertext, so its declared JSON type says nothing about
+             * its column. It's always unbounded text: `maxLength` would truncate the ciphertext,
+             * an enum CHECK would never match it, and jsonb would fail to parse it.
+             */
+            sqlType = DEF_SQL_TYPE;
+            jsonType = 'string';
         }
-        /** A string enum becomes a CHECK — a native PG enum can't drop values and can't be altered in a transaction. */
-        if (property.enum != null && !column.secure && override.type == null
-            && baseType(property) === 'string' && property.enum.every(value => typeof value === 'string')) {
-            const values = property.enum.map(value => `'${value.replace(/'/g, "''")}'`).join(', ');
-            const predicate = column.notNull
-                ? `${quoteIdent(column.column)} IN (${values})`
-                : `${quoteIdent(column.column)} IS NULL OR ${quoteIdent(column.column)} IN (${values})`;
-            checks.push({ name: `${resolvedTable}_${column.column}_enum`, expression: predicate });
+        else if (type === 'array') {
+            const resolved = arraySqlType(property);
+            sqlType = resolved.sqlType;
+            jsonType = resolved.jsonType;
+            array = resolved.array;
         }
-    }
-    const byProperty = {};
-    const byColumn = {};
-    for (const column of columns) {
-        byProperty[column.property] = column;
-        byColumn[column.column] = column;
-    }
-    let primaryKey = [];
-    if (root.primaryKey != null && root.primaryKey.length > 0) {
-        primaryKey = root.primaryKey.map(property => {
-            const column = byProperty[property];
-            if (column == null) {
-                throw new UnsupportedArgumentError(`primary-key:${property}`);
+        else {
+            const resolved = scalarSqlType(property);
+            sqlType = resolved.sqlType;
+            jsonType = resolved.jsonType;
+        }
+        if (override.length != null) {
+            sqlType = `character varying(${override.length})`;
+        }
+        if (override.array === true && !array && !sqlType.endsWith('[]')) {
+            sqlType = `${sqlType}[]`;
+            array = true;
+        }
+        if (override.jsonb === true) {
+            sqlType = DEF_JSON_TYPE;
+            jsonType = jsonType === 'array' ? 'array' : 'object';
+            array = false;
+        }
+        const formatted = toFormatType(sqlType);
+        const isJsonb = formatted === 'jsonb' || formatted === 'json';
+        const column = {
+            property: name,
+            /** No implicit snake_casing — a silent rename is a silent DROP plus ADD. */
+            column: pgIdentifier(override.column ?? name),
+            sqlType: formatted,
+            jsonType,
+            notNull: override.nullable === false ? true : !nullable,
+            primaryKey: override.primaryKey === true,
+            secure,
+            jsonb: isJsonb,
+            array,
+            managed: override.managed !== false,
+            ...(override.using != null ? { using: override.using } : {}),
+            ...(override.comment != null ? { comment: override.comment } : {})
+        };
+        if (override.defaultRaw != null) {
+            column.defaultRaw = override.defaultRaw;
+        }
+        else if (override.default !== undefined) {
+            column.defaultLiteral = override.default;
+        }
+        else if (property.default !== undefined && !isJsonb && !array) {
+            /** Non-scalar defaults stay in `getDefaults()` only — they'd need casting in DDL. */
+            column.defaultLiteral = property.default;
+        }
+        return column;
+    };
+    const collectProperties = (schema) => {
+        const properties = { ...schema.properties };
+        const required = [...(schema.required ?? [])];
+        /** `allOf` composition is used across the framework's schemas — flatten it like mongo does. */
+        for (const part of schema.allOf ?? []) {
+            const nested = collectProperties(part);
+            Object.assign(properties, nested.properties);
+            required.push(...nested.required);
+        }
+        return { properties, required };
+    };
+    /**
+     * Collapse specs that resolved to the same object name, first declaration wins.
+     *
+     * The same index can legitimately be declared twice — a schema-root `pg.indexes` entry, a
+     * per-property `pg: { index: ... }` override and a `resource.index()` call all land in one
+     * list, and nothing stops a declaration from repeating one of the others. Two entries with
+     * one name emit the same `CREATE INDEX` twice inside a single DDL transaction, and Postgres
+     * answers the second with `42P07 already exists` — which rolls back the whole plan, so the
+     * table the first statement created never lands and the resource can never initialize.
+     * Duplicates are a declaration style, not a schema error: dedupe them, don't fail the boot.
+     */
+    const byName = (specs, alias, kind) => {
+        const seen = new Map();
+        for (const spec of specs) {
+            const name = spec.name;
+            if (seen.has(name)) {
+                log.warn('Duplicate declaration, keeping the first one', { resource: alias, kind, name });
+                continue;
             }
-            column.notNull = true;
-            return column.column;
-        });
-    }
-    else {
-        const explicit = columns.filter(column => column.primaryKey);
-        if (explicit.length > 0) {
-            primaryKey = explicit.map(column => {
+            seen.set(name, spec);
+        }
+        return [...seen.values()];
+    };
+    const schemaToTableSpec = (alias, schema, pgSchema, table, autoSync, extraIndexes = []) => {
+        const raw = (schema ?? {});
+        const root = raw[PG_KEYWORD] ?? {};
+        const { properties, required } = collectProperties(raw);
+        const columns = [];
+        const uniques = [...(root.unique ?? [])];
+        const checks = [...(root.checks ?? [])];
+        const indexes = [...(root.indexes ?? []), ...extraIndexes];
+        const references = [];
+        const resolvedTable = pgIdentifier(root.table ?? table);
+        const resolvedSchema = pgIdentifier(root.schema ?? pgSchema);
+        for (const [name, property] of Object.entries(properties)) {
+            const column = compileColumn(name, property, required);
+            columns.push(column);
+            const override = readOverride(property);
+            if (override.unique != null && override.unique !== false) {
+                if (column.secure) {
+                    /**
+                     * Encryption uses a managed nonce, so two identical plaintexts encrypt to different
+                     * ciphertexts — a unique constraint on the column would never collide, silently.
+                     */
+                    throw new UnsupportedArgumentError(`secure-unique:${name}`);
+                }
+                uniques.push({
+                    columns: [name],
+                    ...(typeof override.unique === 'string' ? { name: override.unique } : {})
+                });
+            }
+            if (override.index != null && override.index !== false) {
+                if (column.secure) {
+                    log.warn('Index on a secure column will never match: encryption is non-deterministic', {
+                        resource: alias, column: name,
+                    });
+                }
+                const specs = override.index === true
+                    ? [{ columns: [name] }]
+                    : Array.isArray(override.index) ? override.index : [override.index];
+                indexes.push(...specs.map(spec => ({ ...spec, columns: spec.columns ?? [name] })));
+            }
+            if (override.references != null) {
+                references.push({
+                    ...override.references,
+                    property: name,
+                    column: override.references.column ?? ID_FIELD,
+                    name: pgIdentifier(override.references.name ?? `${resolvedTable}_${column.column}_fkey`)
+                });
+            }
+            if (override.check != null) {
+                checks.push({
+                    name: `${resolvedTable}_${column.column}_check`,
+                    expression: override.check.replace(/\{\{col\}\}/g, quoteIdent(column.column))
+                });
+            }
+            /** A string enum becomes a CHECK — a native PG enum can't drop values and can't be altered in a transaction. */
+            if (property.enum != null && !column.secure && override.type == null
+                && baseType(property) === 'string' && property.enum.every(value => typeof value === 'string')) {
+                const values = property.enum.map(value => `'${value.replace(/'/g, "''")}'`).join(', ');
+                const predicate = column.notNull
+                    ? `${quoteIdent(column.column)} IN (${values})`
+                    : `${quoteIdent(column.column)} IS NULL OR ${quoteIdent(column.column)} IN (${values})`;
+                checks.push({ name: `${resolvedTable}_${column.column}_enum`, expression: predicate });
+            }
+        }
+        const byProperty = {};
+        const byColumn = {};
+        for (const column of columns) {
+            byProperty[column.property] = column;
+            byColumn[column.column] = column;
+        }
+        let primaryKey = [];
+        if (root.primaryKey != null && root.primaryKey.length > 0) {
+            primaryKey = root.primaryKey.map(property => {
+                const column = byProperty[property];
+                if (column == null) {
+                    throw new UnsupportedArgumentError(`primary-key:${property}`);
+                }
                 column.notNull = true;
                 return column.column;
             });
         }
         else {
-            /**
-             * Every OwlMeans record is addressed by `id`, so the column is synthesized when the
-             * schema doesn't declare it — `create()` and `load()` both assume it exists.
-             */
-            let id = byProperty[ID_FIELD];
-            if (id == null) {
-                id = {
-                    property: ID_FIELD, column: ID_FIELD, sqlType: DEF_SQL_TYPE, jsonType: 'string',
-                    notNull: true, primaryKey: true, secure: false, jsonb: false, array: false,
-                    managed: true, defaultRaw: DEF_ID_DEFAULT
-                };
-                columns.unshift(id);
-                byProperty[ID_FIELD] = id;
-                byColumn[ID_FIELD] = id;
+            const explicit = columns.filter(column => column.primaryKey);
+            if (explicit.length > 0) {
+                primaryKey = explicit.map(column => {
+                    column.notNull = true;
+                    return column.column;
+                });
             }
             else {
-                id.notNull = true;
-                id.primaryKey = true;
-                if (id.defaultRaw == null && id.defaultLiteral === undefined) {
-                    id.defaultRaw = id.sqlType === 'uuid' ? 'gen_random_uuid()' : DEF_ID_DEFAULT;
+                /**
+                 * Every OwlMeans record is addressed by `id`, so the column is synthesized when the
+                 * schema doesn't declare it — `create()` and `load()` both assume it exists.
+                 */
+                let id = byProperty[ID_FIELD];
+                if (id == null) {
+                    id = {
+                        property: ID_FIELD, column: ID_FIELD, sqlType: DEF_SQL_TYPE, jsonType: 'string',
+                        notNull: true, primaryKey: true, secure: false, jsonb: false, array: false,
+                        managed: true, defaultRaw: DEF_ID_DEFAULT
+                    };
+                    columns.unshift(id);
+                    byProperty[ID_FIELD] = id;
+                    byColumn[ID_FIELD] = id;
                 }
+                else {
+                    id.notNull = true;
+                    id.primaryKey = true;
+                    if (id.defaultRaw == null && id.defaultLiteral === undefined) {
+                        id.defaultRaw = id.sqlType === 'uuid' ? 'gen_random_uuid()' : DEF_ID_DEFAULT;
+                    }
+                }
+                primaryKey = [id.column];
             }
-            primaryKey = [id.column];
-        }
-    }
-    /** Index and unique specs address properties; map them onto physical columns once, here. */
-    const mapColumns = (names) => names.map(name => {
-        const column = byProperty[name];
-        if (column == null) {
-            throw new UnsupportedArgumentError(`unknown-property:${name}`);
         }
-        return column.column;
-    });
-    const resolvedIndexes = byName(indexes.map(spec => {
-        const list = spec.columns == null
-            ? []
-            : mapColumns(Array.isArray(spec.columns) ? spec.columns : [spec.columns]);
-        const suffix = spec.unique === true ? 'uq' : 'idx';
+        /** Index and unique specs address properties; map them onto physical columns once, here. */
+        const mapColumns = (names) => names.map(name => {
+            const column = byProperty[name];
+            if (column == null) {
+                throw new UnsupportedArgumentError(`unknown-property:${name}`);
+            }
+            return column.column;
+        });
+        const resolvedIndexes = byName(indexes.map(spec => {
+            const list = spec.columns == null
+                ? []
+                : mapColumns(Array.isArray(spec.columns) ? spec.columns : [spec.columns]);
+            const suffix = spec.unique === true ? 'uq' : 'idx';
+            return {
+                ...spec,
+                columns: list,
+                method: spec.method ?? PgIndexMethod.BTree,
+                name: pgIdentifier(spec.name ?? `${resolvedTable}_${list.join('_')}_${suffix}`)
+            };
+        }), alias, 'index');
+        const resolvedUniques = byName(uniques.map(spec => {
+            const list = mapColumns(spec.columns);
+            return { columns: list, name: pgIdentifier(spec.name ?? `${resolvedTable}_${list.join('_')}_key`) };
+        }), alias, 'unique');
         return {
-            ...spec,
-            columns: list,
-            method: spec.method ?? PgIndexMethod.BTree,
-            name: pgIdentifier(spec.name ?? `${resolvedTable}_${list.join('_')}_${suffix}`)
+            alias,
+            schema: resolvedSchema,
+            table: resolvedTable,
+            qualified: qualify(resolvedSchema, resolvedTable),
+            columns,
+            byProperty,
+            byColumn,
+            primaryKey,
+            uniques: resolvedUniques,
+            checks: checks.map(check => ({ ...check, name: pgIdentifier(check.name ?? `${resolvedTable}_check`) })),
+            indexes: resolvedIndexes,
+            references,
+            unmanaged: [
+                ...(root.unmanaged ?? []).map(name => byProperty[name]?.column ?? pgIdentifier(name)),
+                ...columns.filter(column => !column.managed).map(column => column.column)
+            ],
+            autoSync: root.autoSync ?? autoSync,
+            ...(root.comment != null ? { comment: root.comment } : {})
         };
-    }), alias, 'index');
-    const resolvedUniques = byName(uniques.map(spec => {
-        const list = mapColumns(spec.columns);
-        return { columns: list, name: pgIdentifier(spec.name ?? `${resolvedTable}_${list.join('_')}_key`) };
-    }), alias, 'unique');
-    return {
-        alias,
-        schema: resolvedSchema,
-        table: resolvedTable,
-        qualified: qualify(resolvedSchema, resolvedTable),
-        columns,
-        byProperty,
-        byColumn,
-        primaryKey,
-        uniques: resolvedUniques,
-        checks: checks.map(check => ({ ...check, name: pgIdentifier(check.name ?? `${resolvedTable}_check`) })),
-        indexes: resolvedIndexes,
-        references,
-        unmanaged: [
-            ...(root.unmanaged ?? []).map(name => byProperty[name]?.column ?? pgIdentifier(name)),
-            ...columns.filter(column => !column.managed).map(column => column.column)
-        ],
-        autoSync: root.autoSync ?? autoSync,
-        ...(root.comment != null ? { comment: root.comment } : {})
     };
+    return { toFormatType, schemaToTableSpec };
 };
-/**
- * AJV keyword registration for consumers running in strict mode. The mapper reads the raw
- * schema object and never validates through AJV, so this is purely to stop strict mode
- * rejecting a schema that carries `pg` overrides.
- */
-export const pgKeyword = { keyword: PG_KEYWORD, valid: true };
+export const pgSchemaHelper = createPgSchemaHelper();
+/** @deprecated compat:factory-refactor — use `pgSchemaHelper.schemaToTableSpec(…)` */
+export const schemaToTableSpec = (alias, schema, pgSchema, table, autoSync, extraIndexes = []) => pgSchemaHelper.schemaToTableSpec(alias, schema, pgSchema, table, autoSync, extraIndexes);
 //# sourceMappingURL=schema.js.map