@fragno-dev/db 0.2.2 → 0.4.1

package/src/naming/sql-naming.ts

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+
+import type { AnySchema, AnyTable } from "../schema/create";
+
+export type NamespaceScope = "suffix" | "schema";
+
+export interface SqlNamingStrategy {
+  namespaceScope: NamespaceScope;
+  namespaceToSchema: (namespace: string) => string;
+
+  tableName: (logicalTable: string, namespace: string | null) => string;
+  columnName: (logicalColumn: string, logicalTable: string) => string;
+
+  indexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  uniqueIndexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  foreignKeyName: (params: {
+    logicalTable: string;
+    logicalReferencedTable: string;
+    referenceName: string;
+    namespace: string | null;
+  }) => string;
+}
+
+const normalizeNamespace = (namespace: string | null) =>
+  namespace && namespace.length > 0 ? namespace : null;
+
+const buildNamespaceSuffix = (namespace: string | null) => {
+  const sanitized = normalizeNamespace(namespace);
+  return sanitized ? `_${sanitized}` : "";
+};
+
+const MAX_IDENTIFIER_LENGTH = 63;
+const HASH_LENGTH = 8;
+
+const withHash = (value: string) => {
+  const hash = createHash("sha1").update(value).digest("hex").slice(0, 8);
+  return `${value}_${hash}`;
+};
+
+const truncateWithHash = (value: string) => {
+  if (value.length <= MAX_IDENTIFIER_LENGTH) {
+    return value;
+  }
+  const hash = createHash("sha1").update(value).digest("hex").slice(0, HASH_LENGTH);
+  return `${value.slice(0, MAX_IDENTIFIER_LENGTH - HASH_LENGTH)}${hash}`;
+};
+
+const buildIndexName = (
+  prefix: "idx" | "uidx",
+  logicalIndex: string,
+  logicalTable: string,
+  namespace: string | null,
+) => {
+  const base = `${logicalTable}_${logicalIndex}${buildNamespaceSuffix(namespace)}`;
+  return `${prefix}_${withHash(base)}`;
+};
+
+export const suffixNamingStrategy: SqlNamingStrategy = {
+  namespaceScope: "suffix",
+  namespaceToSchema: (namespace) => namespace,
+  tableName: (logicalTable, namespace) => {
+    const sanitized = normalizeNamespace(namespace);
+    return truncateWithHash(sanitized ? `${logicalTable}_${sanitized}` : logicalTable);
+  },
+  columnName: (logicalColumn) => logicalColumn,
+  indexName: (logicalIndex, logicalTable, namespace) =>
+    truncateWithHash(buildIndexName("idx", logicalIndex, logicalTable, namespace)),
+  uniqueIndexName: (logicalIndex, logicalTable, namespace) =>
+    truncateWithHash(buildIndexName("uidx", logicalIndex, logicalTable, namespace)),
+  foreignKeyName: ({ logicalTable, logicalReferencedTable, referenceName, namespace }) => {
+    const base = `${logicalTable}_${logicalReferencedTable}_${referenceName}${buildNamespaceSuffix(namespace)}`;
+    return truncateWithHash(`fk_${withHash(base)}`);
+  },
+};
+
+export const schemaNamingStrategy: SqlNamingStrategy = {
+  namespaceScope: "schema",
+  namespaceToSchema: (namespace) => namespace,
+  tableName: (logicalTable) => truncateWithHash(logicalTable),
+  columnName: (logicalColumn) => logicalColumn,
+  indexName: (logicalIndex) => truncateWithHash(logicalIndex),
+  uniqueIndexName: (logicalIndex) => truncateWithHash(logicalIndex),
+  foreignKeyName: ({ logicalTable, logicalReferencedTable, referenceName }) =>
+    truncateWithHash(`fk_${logicalTable}_${logicalReferencedTable}_${referenceName}`),
+};
+
+export class NamingResolver {
+  readonly #namespace: string | null;
+  readonly #strategy: SqlNamingStrategy;
+  readonly #tableNameMap: Record<string, string> = {};
+  readonly #columnNameMaps = new Map<string, Record<string, string>>();
+
+  constructor(schema: AnySchema, namespace: string | null, strategy: SqlNamingStrategy) {
+    this.#namespace = namespace;
+    this.#strategy = strategy;
+
+    for (const table of Object.values(schema.tables)) {
+      const physicalTable = this.getTableName(table.name);
+      this.#tableNameMap[physicalTable] = table.name;
+
+      const columnMap: Record<string, string> = {};
+      for (const column of Object.values(table.columns)) {
+        const physicalColumn = this.getColumnName(table.name, column.name);
+        columnMap[physicalColumn] = column.name;
+      }
+      this.#columnNameMaps.set(table.name, columnMap);
+    }
+  }
+
+  get namespace(): string | null {
+    return this.#namespace;
+  }
+
+  get strategy(): SqlNamingStrategy {
+    return this.#strategy;
+  }
+
+  getSchemaName(): string | null {
+    if (this.#strategy.namespaceScope !== "schema") {
+      return null;
+    }
+    if (!this.#namespace || this.#namespace.length === 0) {
+      return null;
+    }
+    return this.#strategy.namespaceToSchema(this.#namespace);
+  }
+
+  getTableName(logicalTable: string): string {
+    return this.#strategy.tableName(logicalTable, this.#namespace);
+  }
+
+  getColumnName(logicalTable: string, logicalColumn: string): string {
+    return this.#strategy.columnName(logicalColumn, logicalTable);
+  }
+
+  getIndexName(logicalIndex: string, logicalTable: string): string {
+    return this.#strategy.indexName(logicalIndex, logicalTable, this.#namespace);
+  }
+
+  getUniqueIndexName(logicalIndex: string, logicalTable: string): string {
+    return this.#strategy.uniqueIndexName(logicalIndex, logicalTable, this.#namespace);
+  }
+
+  getForeignKeyName(params: {
+    logicalTable: string;
+    logicalReferencedTable: string;
+    referenceName: string;
+  }): string {
+    return this.#strategy.foreignKeyName({
+      ...params,
+      namespace: this.#namespace,
+    });
+  }
+
+  getTableNameMap(): Record<string, string> {
+    return { ...this.#tableNameMap };
+  }
+
+  getColumnNameMap(table: AnyTable | string): Record<string, string> {
+    const tableName = typeof table === "string" ? table : table.name;
+    const map = this.#columnNameMaps.get(tableName);
+    return map ? { ...map } : {};
+  }
+}
+
+export const createNamingResolver = (
+  schema: AnySchema,
+  namespace: string | null,
+  strategy: SqlNamingStrategy,
+): NamingResolver => new NamingResolver(schema, namespace, strategy);
+
+/**
+ * Sanitizes a namespace for use in SQL identifiers and TypeScript exports.
+ * Converts dashes to underscores to ensure compatibility with SQL identifiers.
+ *
+ * @example
+ * sanitizeNamespace("my-fragment") // => "my_fragment"
+ */
+export function sanitizeNamespace(namespace: string): string {
+  return namespace.replace(/-/g, "_");
+}

package/src/outbox/outbox-builder.ts

@@ -0,0 +1,241 @@
+import { internalSchema } from "../fragments/internal-fragment.schema";
+import type { MutationOperation } from "../query/unit-of-work/unit-of-work";
+import type { AnySchema, AnyTable } from "../schema/create";
+import { FragnoId, FragnoReference } from "../schema/create";
+import type { OutboxRefLookup, OutboxPayload, OutboxMutation } from "./outbox";
+import { encodeVersionstamp, versionstampToHex } from "./outbox";
+
+const INTERNAL_TABLE_NAMES = new Set(Object.keys(internalSchema.tables));
+
+type OutboxMutationDraft = OutboxMutation extends infer T
+  ? T extends OutboxMutation
+    ? Omit<T, "versionstamp"> & { versionstamp?: string }
+    : never
+  : never;
+
+export type OutboxPlan = {
+  drafts: OutboxMutationDraft[];
+  lookups: OutboxRefLookup[];
+};
+
+export function buildOutboxPlan(operations: MutationOperation<AnySchema>[]): OutboxPlan {
+  const drafts: OutboxMutationDraft[] = [];
+  const lookups: OutboxRefLookup[] = [];
+
+  for (const op of operations) {
+    if (op.type === "check") {
+      continue;
+    }
+
+    if (isInternalMutation(op)) {
+      continue;
+    }
+
+    const table = getTable(op.schema, op.table);
+    const schemaName = op.namespace ?? "";
+    const namespace = op.namespace ? op.namespace : undefined;
+    const mutationIndex = drafts.length;
+
+    if (op.type === "create") {
+      drafts.push({
+        op: "create",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: op.generatedExternalId,
+        values: encodeOutboxValues({
+          table,
+          values: op.values,
+          mutationIndex,
+          namespace,
+          lookups,
+        }),
+      });
+      continue;
+    }
+
+    if (op.type === "update") {
+      drafts.push({
+        op: "update",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: getExternalId(op.id),
+        set: encodeOutboxValues({
+          table,
+          values: op.set,
+          mutationIndex,
+          namespace,
+          lookups,
+        }),
+        checkVersion: op.checkVersion && op.id instanceof FragnoId ? op.id.version : undefined,
+      });
+      continue;
+    }
+
+    if (op.type === "delete") {
+      drafts.push({
+        op: "delete",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: getExternalId(op.id),
+        checkVersion: op.checkVersion && op.id instanceof FragnoId ? op.id.version : undefined,
+      });
+    }
+  }
+
+  return { drafts, lookups };
+}
+
+export function finalizeOutboxPayload(plan: OutboxPlan, transactionVersion: bigint): OutboxPayload {
+  const mutations: OutboxMutation[] = plan.drafts.map((draft, index) => {
+    const versionstamp = versionstampToHex(encodeVersionstamp(transactionVersion, index));
+    return { ...draft, versionstamp };
+  });
+
+  return {
+    version: 1,
+    mutations,
+  };
+}
+
+function encodeOutboxValues(options: {
+  table: AnyTable;
+  values: Record<string, unknown>;
+  mutationIndex: number;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): Record<string, unknown> {
+  const { table, values, mutationIndex, namespace, lookups } = options;
+  const output: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    const column = table.columns[key];
+
+    if (column?.role === "reference") {
+      const resolved = resolveReferenceValue({
+        value,
+        mutationIndex,
+        columnName: key,
+        table,
+        namespace,
+        lookups,
+      });
+      output[key] = resolved;
+      continue;
+    }
+
+    if (value instanceof FragnoId) {
+      output[key] = value.externalId;
+      continue;
+    }
+
+    output[key] = value;
+  }
+
+  return output;
+}
+
+function resolveReferenceValue(options: {
+  value: unknown;
+  mutationIndex: number;
+  columnName: string;
+  table: AnyTable;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): unknown {
+  const { value, mutationIndex, columnName, table, namespace, lookups } = options;
+
+  if (value === null) {
+    return null;
+  }
+
+  if (value instanceof FragnoId) {
+    return value.externalId;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value instanceof FragnoReference) {
+    return createReferencePlaceholder({
+      internalId: value.internalId,
+      mutationIndex,
+      columnName,
+      table,
+      namespace,
+      lookups,
+    });
+  }
+
+  if (typeof value === "bigint" || typeof value === "number") {
+    return createReferencePlaceholder({
+      internalId: value,
+      mutationIndex,
+      columnName,
+      table,
+      namespace,
+      lookups,
+    });
+  }
+
+  return value;
+}
+
+function createReferencePlaceholder(options: {
+  internalId: bigint | number;
+  mutationIndex: number;
+  columnName: string;
+  table: AnyTable;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): { __fragno_ref: string } {
+  const { internalId, mutationIndex, columnName, table, namespace, lookups } = options;
+  const key = `${mutationIndex}.${columnName}`;
+  const referencedTable = resolveReferencedTable(table, columnName);
+
+  lookups.push({
+    key,
+    internalId,
+    table: referencedTable,
+    namespace,
+  });
+
+  return { __fragno_ref: key };
+}
+
+function resolveReferencedTable(table: AnyTable, columnName: string): AnyTable {
+  for (const relation of Object.values(table.relations)) {
+    if (relation.on.some(([localColumn]) => localColumn === columnName)) {
+      return relation.table;
+    }
+  }
+
+  throw new Error(`Reference column ${columnName} not found in table ${table.name}`);
+}
+
+function getExternalId(id: FragnoId | string): string {
+  return typeof id === "string" ? id : id.externalId;
+}
+
+function isInternalMutation(op: MutationOperation<AnySchema>): boolean {
+  if (op.schema === internalSchema) {
+    return true;
+  }
+
+  return op.namespace === "" && INTERNAL_TABLE_NAMES.has(op.table);
+}
+
+function getTable(schema: AnySchema, tableName: string): AnyTable {
+  const table = schema.tables[tableName];
+  if (!table) {
+    throw new Error(`Invalid table name ${tableName}.`);
+  }
+  return table;
+}