kysely-ddl 0.1.0

package/dist/table/identifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Postgres object names are limited to `NAMEDATALEN - 1` = **63 bytes**.
+ * Anything longer is silently truncated, which is more dangerous than it looks:
+ * the snapshot remembers the long name, the database holds the short one, and
+ * the next diff keeps trying to create the "missing" index forever.
+ *
+ * Hence two different behaviours:
+ *
+ *   explicit name  -> an error, so the author sees the problem and shortens it;
+ *   auto-name      -> shortened deterministically with a hash suffix, so that
+ *                     two long names do not collapse into one.
+ */
+export declare const MAX_IDENTIFIER_BYTES = 63;
+/**
+ * Shortens an auto-name to the postgres limit. The hash suffix is computed from
+ * the FULL name, so two different long names with a common prefix do not collapse.
+ */
+export declare function fitIdentifier(name: string): string;
+/** An explicit name is left alone, but exceeding the limit must not pass silently. */
+export declare function assertIdentifier(name: string, what: string): void;
+/**
+ * An auto-name in the `{table}_{columns}_{suffix}` style:
+ * `user_resource_transaction_user_id_resource_idx`.
+ */
+export declare function autoName(parts: readonly string[], suffix: string): string;

package/dist/table/identifier.js

@@ -0,0 +1,58 @@
+/**
+ * Postgres object names are limited to `NAMEDATALEN - 1` = **63 bytes**.
+ * Anything longer is silently truncated, which is more dangerous than it looks:
+ * the snapshot remembers the long name, the database holds the short one, and
+ * the next diff keeps trying to create the "missing" index forever.
+ *
+ * Hence two different behaviours:
+ *
+ *   explicit name  -> an error, so the author sees the problem and shortens it;
+ *   auto-name      -> shortened deterministically with a hash suffix, so that
+ *                     two long names do not collapse into one.
+ */
+export const MAX_IDENTIFIER_BYTES = 63;
+function byteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+/** FNV-1a: a stable short hash is all that is needed, cryptography is irrelevant here. */
+function hash(value) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        h ^= value.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/**
+ * Shortens an auto-name to the postgres limit. The hash suffix is computed from
+ * the FULL name, so two different long names with a common prefix do not collapse.
+ */
+export function fitIdentifier(name) {
+    if (byteLength(name) <= MAX_IDENTIFIER_BYTES) {
+        return name;
+    }
+    const suffix = `_${hash(name)}`;
+    let head = name;
+    while (byteLength(head) + suffix.length > MAX_IDENTIFIER_BYTES) {
+        head = head.slice(0, -1);
+    }
+    return `${head.replace(/_+$/, '')}${suffix}`;
+}
+/** An explicit name is left alone, but exceeding the limit must not pass silently. */
+export function assertIdentifier(name, what) {
+    const length = byteLength(name);
+    if (length > MAX_IDENTIFIER_BYTES) {
+        throw new Error(`${what}: name "${name}" is ${length} bytes long, postgres would truncate it to ` +
+            `${MAX_IDENTIFIER_BYTES}. Shorten it or drop it to have it generated.`);
+    }
+    if (name.length === 0) {
+        throw new Error(`${what}: empty name`);
+    }
+}
+/**
+ * An auto-name in the `{table}_{columns}_{suffix}` style:
+ * `user_resource_transaction_user_id_resource_idx`.
+ */
+export function autoName(parts, suffix) {
+    return fitIdentifier([...parts, suffix].join('_'));
+}

package/dist/table/sql.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A minimal SQL fragment: everything needed for defaults, check expressions
+ * and partial index conditions.
+ *
+ * The fragment is stored as chunks rather than a string, so that a column
+ * reference can be rendered with its DATABASE NAME (`"user_id"`) instead of
+ * the property name.
+ */
+/** A column reference inside an expression. */
+export interface ColumnRef {
+    readonly kind: 'column';
+    /** The column name in the database. */
+    readonly name: string;
+}
+/** A literal that must be escaped when rendered. */
+export interface Literal {
+    readonly kind: 'literal';
+    readonly value: string | number | boolean | null;
+}
+export type SqlChunk = string | ColumnRef | Literal;
+export interface Sql {
+    readonly kind: 'sql';
+    readonly chunks: readonly SqlChunk[];
+}
+export declare function isSql(value: unknown): value is Sql;
+/**
+ * ```ts
+ * sql`${c.delta} <> 0`
+ * sql`uuidv7()`
+ * ```
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): Sql;
+/** `"status" in ('new', 'closed')`: the most common form of a check in real schemas. */
+export declare function inArray(column: ColumnRef, values: readonly (string | number)[]): Sql;
+/**
+ * Column names referenced by the expression, in order of first appearance.
+ * Needed to build a check constraint name: `{table}_{columns}_check`.
+ */
+export declare function collectColumns(expr: Sql): string[];
+export declare function quoteIdentifier(name: string): string;
+export declare function quoteLiteral(value: string | number | boolean | null): string;
+/** Expands the fragment into an SQL string. */
+export declare function renderSql(expr: Sql): string;

package/dist/table/sql.js

@@ -0,0 +1,115 @@
+/**
+ * A minimal SQL fragment: everything needed for defaults, check expressions
+ * and partial index conditions.
+ *
+ * The fragment is stored as chunks rather than a string, so that a column
+ * reference can be rendered with its DATABASE NAME (`"user_id"`) instead of
+ * the property name.
+ */
+export function isSql(value) {
+    return typeof value === 'object' && value !== null && value.kind === 'sql';
+}
+/** For error messages: objects as JSON, everything else as is. */
+function describeValue(value) {
+    switch (typeof value) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+        case 'symbol':
+        case 'undefined':
+            return String(value);
+        case 'function':
+            return 'function';
+        default:
+            return JSON.stringify(value);
+    }
+}
+function toChunk(value) {
+    if (isSql(value)) {
+        // nested fragments would be expanded on render; a marker is enough here
+        throw new Error('nested sql`` is not supported: build the expression as a single template');
+    }
+    if (typeof value === 'object' && value !== null && value.kind === 'column') {
+        return value;
+    }
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null) {
+        return { kind: 'literal', value };
+    }
+    throw new Error(`cannot interpolate into sql\`\`: ${describeValue(value)}`);
+}
+/**
+ * ```ts
+ * sql`${c.delta} <> 0`
+ * sql`uuidv7()`
+ * ```
+ */
+export function sql(strings, ...values) {
+    const chunks = [];
+    strings.forEach((part, i) => {
+        if (part) {
+            chunks.push(part);
+        }
+        if (i < values.length) {
+            chunks.push(toChunk(values[i]));
+        }
+    });
+    return { kind: 'sql', chunks };
+}
+/** `"status" in ('new', 'closed')`: the most common form of a check in real schemas. */
+export function inArray(column, values) {
+    const chunks = [column, ' in ('];
+    values.forEach((value, i) => {
+        if (i > 0) {
+            chunks.push(', ');
+        }
+        chunks.push({ kind: 'literal', value });
+    });
+    chunks.push(')');
+    return { kind: 'sql', chunks };
+}
+/**
+ * Column names referenced by the expression, in order of first appearance.
+ * Needed to build a check constraint name: `{table}_{columns}_check`.
+ */
+export function collectColumns(expr) {
+    const names = [];
+    for (const chunk of expr.chunks) {
+        if (typeof chunk !== 'string' && chunk.kind === 'column' && !names.includes(chunk.name)) {
+            names.push(chunk.name);
+        }
+    }
+    return names;
+}
+export function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export function quoteLiteral(value) {
+    if (value === null) {
+        return 'NULL';
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Expands the fragment into an SQL string. */
+export function renderSql(expr) {
+    return expr.chunks
+        .map(chunk => {
+        if (typeof chunk === 'string') {
+            return chunk;
+        }
+        if (chunk.kind === 'column') {
+            return quoteIdentifier(chunk.name);
+        }
+        return quoteLiteral(chunk.value);
+    })
+        .join('');
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "kysely-ddl",
+  "version": "0.1.0",
+  "description": "PostgreSQL schema as TypeScript code: SQL migrations from snapshot diffs, Kysely table types and a migration runner",
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "kysely",
+    "migrations",
+    "schema",
+    "ddl",
+    "schema-as-code",
+    "bun",
+    "typescript"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hehmonke/kysely-ddl.git"
+  },
+  "homepage": "https://github.com/hehmonke/kysely-ddl#readme",
+  "bugs": {
+    "url": "https://github.com/hehmonke/kysely-ddl/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kysely": {
+      "types": "./dist/kysely/index.d.ts",
+      "default": "./dist/kysely/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "smoke:node": "node scripts/smoke-node.mjs",
+    "check": "bun run typecheck && bun run lint && bun test && bun run build",
+    "db:up": "docker compose up -d --wait",
+    "db:down": "docker compose down -v",
+    "prepublishOnly": "bun run check"
+  },
+  "peerDependencies": {
+    "kysely": ">=0.28"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "^1.80.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.4.0",
+    "@types/pg": "^8.23.1",
+    "eslint-plugin-perfectionist": "^5.10.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "kysely": "^0.29.5",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "pg": "^8.23.0",
+    "typescript": "^7.0.2"
+  }
+}