@manablox/db 0.1.0

package/migrations/meta/_journal.json

@@ -0,0 +1,41 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1788506703488,
+      "tag": "0000_init",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1788506841571,
+      "tag": "0001_permalink-path",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1788508162118,
+      "tag": "0002_account-issuer",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1788514181873,
+      "tag": "0003_asset-usages",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1788544039067,
+      "tag": "0004_apikey-spaces",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@manablox/db",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/core": "0.1.0",
+    "drizzle-orm": "^0.45.2",
+    "postgres": "^3.4.9"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@types/node": "^26.4.1",
+    "drizzle-kit": "^0.31.10",
+    "testcontainers": "^12.1.0",
+    "tsx": "^4.20.7",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "generate": "drizzle-kit generate",
+    "migrate": "tsx src/cli/migrate.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,13 @@
+import type { Sql } from './client.js';
+
+/**
+ * Extensions the schema depends on. Run before the generated migrations, which
+ * reference `ltree` columns and `pg_trgm` operator classes.
+ */
+export async function applyBootstrapSql(sql: Sql): Promise<void> {
+  await sql.unsafe(`
+    create extension if not exists "ltree";
+    create extension if not exists "pg_trgm";
+    create extension if not exists "btree_gin";
+  `);
+}

package/src/cli/migrate.ts

@@ -0,0 +1,24 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import { applyBootstrapSql } from '../bootstrap.js';
+import { createDatabase } from '../client.js';
+
+const migrationsFolder = resolve(dirname(fileURLToPath(import.meta.url)), '../../migrations');
+
+const url = process.env.DATABASE_URL;
+if (!url) {
+  console.error('DATABASE_URL is required');
+  process.exit(1);
+}
+
+const handle = createDatabase({ url, max: 1 });
+
+try {
+  // Extensions must exist before the generated migrations reference ltree columns.
+  await applyBootstrapSql(handle.sql);
+  await migrate(handle.db, { migrationsFolder });
+  console.info('migrations applied');
+} finally {
+  await handle.close();
+}

package/src/client.ts

@@ -0,0 +1,37 @@
+import type { DatabaseConfig } from '@manablox/core';
+import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema.js';
+
+export type Database = PostgresJsDatabase<typeof schema>;
+export type Sql = ReturnType<typeof postgres>;
+
+export interface DatabaseHandle {
+  db: Database;
+  sql: Sql;
+  close: () => Promise<void>;
+}
+
+export interface DatabaseOptions {
+  /** Called once per statement sent to Postgres. Used by tests to assert query counts. */
+  onQuery?: (query: string) => void;
+}
+
+export function createDatabase(
+  config: DatabaseConfig,
+  options: DatabaseOptions = {},
+): DatabaseHandle {
+  const sql = postgres(config.url, {
+    max: config.max ?? 10,
+    ...(options.onQuery ? { debug: (_c: number, query: string) => options.onQuery?.(query) } : {}),
+    ...(config.ssl ? { ssl: 'require' as const } : {}),
+    // `ltree` and `tsvector` have no client-side parser, so postgres.js returns them as
+    // strings — which is exactly what the schema declares. Do not pass `types: {}` here:
+    // it replaces the built-in serialisers wholesale and Date parameters stop working.
+    onnotice: () => {},
+  });
+
+  const db = drizzle(sql, { schema, casing: 'snake_case' });
+
+  return { db, sql, close: () => sql.end({ timeout: 5 }) };
+}

package/src/columns.ts

@@ -0,0 +1,39 @@
+import { customType } from 'drizzle-orm/pg-core';
+
+/**
+ * `ltree` — the materialised ancestor path of a content node. A subtree move is one
+ * `UPDATE ... SET path = :newParent || subpath(path, nlevel(:oldParent))`.
+ */
+export const ltree = customType<{ data: string; driverData: string }>({
+  dataType: () => 'ltree',
+});
+
+/** `tsvector` — generated from `title` + `search_text`, never written directly. */
+export const tsvector = customType<{ data: string; driverData: string }>({
+  dataType: () => 'tsvector',
+});
+
+/**
+ * ltree labels accept only `[A-Za-z0-9_]`, so UUID hyphens are swapped for underscores.
+ * The transform is total and reversible.
+ */
+export const idToLabel = (id: string): string => id.replaceAll('-', '_');
+export const labelToId = (label: string): string => {
+  const hex = label.replaceAll('_', '');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+};
+
+/** Builds the path of a node from its ancestors' ids (root first) plus its own. */
+export const buildPath = (ancestorIds: string[], selfId: string): string =>
+  [...ancestorIds, selfId].map(idToLabel).join('.');
+
+/** Splits a stored path back into ids, root first, self last. */
+export const parsePath = (path: string): string[] => path.split('.').filter(Boolean).map(labelToId);
+
+export const pathDepth = (path: string): number => (path ? path.split('.').length : 0);

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './bootstrap.js';
+export * from './client.js';
+export * from './columns.js';
+export * from './query.js';
+export * from './repositories/asset.js';
+export * from './repositories/asset-usage.js';
+export * from './repositories/content.js';
+export * from './repositories/content-type.js';
+export * from './repositories/index.js';
+export * from './repositories/space.js';
+export * from './repositories/user.js';
+export * as schema from './schema.js';
+export * from './schema.js';

package/src/query.ts

@@ -0,0 +1,217 @@
+import { type ContentTypeRegistry, type FilterOperator, ManabloxError } from '@manablox/core';
+import { and, eq, inArray, isNull, type SQL, sql } from 'drizzle-orm';
+import type { PgColumn } from 'drizzle-orm/pg-core';
+import type { contents, publishedContents } from './schema.js';
+
+/**
+ * Both content tables share a column set, so one filter builder serves the draft and
+ * the published projection. Typing the parameter as the union (rather than `PgTable`)
+ * keeps real column references, which is what lets Drizzle bind arrays and UUIDs
+ * correctly instead of stringifying them into the SQL text.
+ */
+export type ContentTable = typeof contents | typeof publishedContents;
+
+/**
+ * Note on `?: T | undefined` throughout the input types in this file: the workspace runs
+ * with `exactOptionalPropertyTypes`, under which a bare `?:` accepts an absent property
+ * but rejects an explicit `undefined`. Validators (Zod, and any Standard Schema) produce
+ * exactly that explicit `undefined` for optional fields, so input DTOs widen while the
+ * domain types they feed stay strict.
+ */
+export interface FieldFilter {
+  /** Field machine name on the content type. */
+  name: string;
+  op: FilterOperator;
+  value?: unknown | undefined;
+}
+
+export interface ContentFilter {
+  spaceId?: string | undefined;
+  /** Content type ids. */
+  typeIds?: string[] | undefined;
+  locale?: string | undefined;
+  status?: 'draft' | 'published' | 'archived' | undefined;
+  ids?: string[] | undefined;
+  parentId?: string | null | undefined;
+  /** Restrict to the subtree below this content id (inclusive of its descendants). */
+  under?: string | undefined;
+  slug?: string | undefined;
+  permalink?: string | undefined;
+  localizationId?: string | undefined;
+  visibleInMenu?: boolean | undefined;
+  /** Full-text query against `title` + field contributions. */
+  search?: string | undefined;
+  fields?: FieldFilter[] | undefined;
+}
+
+export interface ContentSort {
+  by: 'position' | 'title' | 'createdAt' | 'updatedAt' | 'publishedAt' | 'slug';
+  direction: 'asc' | 'desc';
+}
+
+export interface Pagination {
+  limit: number;
+  offset: number;
+}
+
+const SORT_COLUMNS: Record<ContentSort['by'], string> = {
+  position: 'position',
+  title: 'title',
+  createdAt: 'created_at',
+  updatedAt: 'updated_at',
+  publishedAt: 'published_at',
+  slug: 'slug',
+};
+
+/**
+ * Translates a filter into SQL. Every field predicate is checked against the field
+ * type's declared `filters` list first: an unsupported operator is a 400, and every
+ * supported one has an index behind it.
+ */
+export function buildContentWhere(
+  table: ContentTable,
+  filter: ContentFilter,
+  registry: ContentTypeRegistry,
+): SQL | undefined {
+  const conditions: SQL[] = [];
+
+  if (filter.spaceId) conditions.push(eq(table.spaceId, filter.spaceId));
+  if (filter.locale) conditions.push(eq(table.locale, filter.locale));
+  if (filter.status) conditions.push(eq(table.status, filter.status));
+  if (filter.localizationId) conditions.push(eq(table.localizationId, filter.localizationId));
+  if (filter.slug) conditions.push(eq(table.slug, filter.slug));
+  if (filter.permalink !== undefined) conditions.push(eq(table.permalink, filter.permalink));
+  if (filter.visibleInMenu !== undefined) {
+    conditions.push(eq(table.visibleInMenu, filter.visibleInMenu));
+  }
+  if (filter.typeIds?.length) conditions.push(inArray(table.typeId, filter.typeIds));
+  if (filter.ids?.length) conditions.push(inArray(table.id, filter.ids));
+
+  if (filter.parentId !== undefined) {
+    conditions.push(
+      filter.parentId === null ? isNull(table.parentId) : eq(table.parentId, filter.parentId),
+    );
+  }
+
+  if (filter.under) {
+    // GiST-indexed ancestor test — the whole subtree without a recursive query.
+    conditions.push(
+      sql`${table.path} <@ (select path from ${table} where id = ${filter.under}::uuid)`,
+    );
+  }
+
+  if (filter.search) {
+    conditions.push(sql`${table.search} @@ websearch_to_tsquery('simple', ${filter.search})`);
+  }
+
+  for (const fieldFilter of filter.fields ?? []) {
+    conditions.push(buildFieldCondition(table, fieldFilter, filter.typeIds ?? [], registry));
+  }
+
+  return conditions.length > 0 ? and(...conditions) : undefined;
+}
+
+function buildFieldCondition(
+  table: ContentTable,
+  filter: FieldFilter,
+  typeIds: string[],
+  registry: ContentTypeRegistry,
+): SQL {
+  assertOperatorAllowed(filter, typeIds, registry);
+
+  const path = sql`${table.fields} -> ${filter.name}`;
+  const text = sql`${table.fields} ->> ${filter.name}`;
+
+  switch (filter.op) {
+    case 'eq':
+      // jsonb containment, so the `jsonb_path_ops` GIN index can serve it.
+      return sql`${table.fields} @> jsonb_build_object(${filter.name}::text, ${JSON.stringify(filter.value ?? null)}::jsonb)`;
+    case 'neq':
+      return sql`not (${table.fields} @> jsonb_build_object(${filter.name}::text, ${JSON.stringify(filter.value ?? null)}::jsonb))`;
+    case 'in':
+      return sql`${text} = any(${sql.param(asStringArray(filter.value))}::text[])`;
+    case 'notIn':
+      return sql`${text} <> all(${sql.param(asStringArray(filter.value))}::text[])`;
+    case 'lt':
+      return sql`(${text})::numeric < ${asNumber(filter.value)}`;
+    case 'lte':
+      return sql`(${text})::numeric <= ${asNumber(filter.value)}`;
+    case 'gt':
+      return sql`(${text})::numeric > ${asNumber(filter.value)}`;
+    case 'gte':
+      return sql`(${text})::numeric >= ${asNumber(filter.value)}`;
+    case 'contains':
+      return sql`${text} ilike ${`%${escapeLike(String(filter.value ?? ''))}%`}`;
+    case 'startsWith':
+      return sql`${text} ilike ${`${escapeLike(String(filter.value ?? ''))}%`}`;
+    case 'endsWith':
+      return sql`${text} ilike ${`%${escapeLike(String(filter.value ?? ''))}`}`;
+    case 'isNull':
+      return sql`(${path} is null or ${path} = 'null'::jsonb)`;
+    case 'isNotNull':
+      return sql`(${path} is not null and ${path} <> 'null'::jsonb)`;
+    default: {
+      const exhaustive: never = filter.op;
+      throw ManabloxError.badRequest('query.operator.unsupported', { op: exhaustive });
+    }
+  }
+}
+
+/**
+ * A field predicate is only accepted when *every* candidate content type declares a
+ * field of that name whose field type supports the operator.
+ */
+function assertOperatorAllowed(
+  filter: FieldFilter,
+  typeIds: string[],
+  registry: ContentTypeRegistry,
+): void {
+  const candidates =
+    typeIds.length > 0 ? typeIds.map((id) => registry.get(id)) : registry.contentTypes;
+
+  const matching = candidates
+    .map((type) => type.fields.find((field) => field.name === filter.name))
+    .filter((field): field is NonNullable<typeof field> => field !== undefined);
+
+  if (matching.length === 0) {
+    throw ManabloxError.badRequest('query.field.unknown', { field: filter.name });
+  }
+
+  for (const field of matching) {
+    const fieldType = registry.fieldTypes.tryGet(field.type);
+    if (!fieldType?.filters.includes(filter.op)) {
+      throw ManabloxError.badRequest('query.operator.unsupported', {
+        field: filter.name,
+        fieldType: field.type,
+        op: filter.op,
+      });
+    }
+  }
+}
+
+export function buildOrderBy(sorts: ContentSort[]): SQL {
+  if (sorts.length === 0) {
+    return sql`${sql.identifier('position')} asc, ${sql.identifier('created_at')} asc`;
+  }
+  const parts = sorts.map((sort) => {
+    const column = SORT_COLUMNS[sort.by];
+    if (!column) throw ManabloxError.badRequest('query.sort.unsupported', { by: sort.by });
+    return sql`${sql.identifier(column)} ${sql.raw(sort.direction === 'desc' ? 'desc' : 'asc')}`;
+  });
+  return parts.reduce((acc, part) => sql`${acc}, ${part}`);
+}
+
+const escapeLike = (value: string): string => value.replace(/[%_\\]/g, (c) => `\\${c}`);
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) throw ManabloxError.badRequest('query.value.expectedArray');
+  return value.map((entry) => String(entry));
+}
+
+function asNumber(value: unknown): number {
+  const parsed = Number(value);
+  if (Number.isNaN(parsed)) throw ManabloxError.badRequest('query.value.expectedNumber');
+  return parsed;
+}
+
+export type { PgColumn };

package/src/repositories/asset-usage.ts

@@ -0,0 +1,166 @@
+import { and, eq, inArray, notInArray, sql } from 'drizzle-orm';
+import type { Database } from '../client.js';
+import { assetUsages, contents, publishedContents } from '../schema.js';
+
+/**
+ * The asset → document reachability index.
+ *
+ * `published` tracks the *published projection*, not the draft: a draft that adds an
+ * image does not make that image public, and a draft that removes one does not make it
+ * private until the change is published. Every method below preserves that distinction,
+ * which is why the column exists rather than the table simply holding published rows.
+ */
+export class AssetUsageRepository {
+  constructor(private readonly db: Database) {}
+
+  /** The subset of `assetIds` reachable from at least one published document. */
+  async filterPublished(assetIds: string[]): Promise<Set<string>> {
+    if (assetIds.length === 0) return new Set();
+    const rows = await this.db
+      .selectDistinct({ assetId: assetUsages.assetId })
+      .from(assetUsages)
+      .where(and(inArray(assetUsages.assetId, assetIds), eq(assetUsages.published, true)));
+    return new Set(rows.map((row) => row.assetId));
+  }
+
+  async forContent(contentId: string): Promise<Array<{ assetId: string; published: boolean }>> {
+    return this.db
+      .select({ assetId: assetUsages.assetId, published: assetUsages.published })
+      .from(assetUsages)
+      .where(eq(assetUsages.contentId, contentId));
+  }
+
+  /**
+   * Records what a *draft* references.
+   *
+   * Rows the draft dropped are removed only if they are not currently published —
+   * otherwise editing a draft would silently revoke access to an image the live page is
+   * still showing.
+   */
+  async recordDraft(contentId: string, spaceId: string, assetIds: string[]): Promise<void> {
+    const unique = [...new Set(assetIds)];
+
+    await this.db.transaction(async (tx) => {
+      await tx
+        .delete(assetUsages)
+        .where(
+          and(
+            eq(assetUsages.contentId, contentId),
+            eq(assetUsages.published, false),
+            ...(unique.length > 0 ? [notInArray(assetUsages.assetId, unique)] : []),
+          ),
+        );
+
+      if (unique.length === 0) return;
+
+      await tx
+        .insert(assetUsages)
+        .values(
+          unique.map((assetId) => ({
+            assetId,
+            contentId,
+            spaceId,
+            published: false,
+            updatedAt: new Date(),
+          })),
+        )
+        // A row that is already published stays published: this write describes the
+        // draft, and `onConflictDoNothing` is the difference between recording a draft
+        // and revoking a live asset.
+        .onConflictDoNothing();
+    });
+  }
+
+  /**
+   * Records what the published projection references.
+   *
+   * Assets the new revision no longer uses lose their published flag but keep their row
+   * when the draft still references them, so the admin's "where is this used" view stays
+   * complete.
+   */
+  async recordPublished(contentId: string, spaceId: string, assetIds: string[]): Promise<void> {
+    const unique = [...new Set(assetIds)];
+
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(assetUsages)
+        .set({ published: false, updatedAt: new Date() })
+        .where(
+          and(
+            eq(assetUsages.contentId, contentId),
+            ...(unique.length > 0 ? [notInArray(assetUsages.assetId, unique)] : []),
+          ),
+        );
+
+      if (unique.length === 0) return;
+
+      await tx
+        .insert(assetUsages)
+        .values(
+          unique.map((assetId) => ({
+            assetId,
+            contentId,
+            spaceId,
+            published: true,
+            updatedAt: new Date(),
+          })),
+        )
+        .onConflictDoUpdate({
+          target: [assetUsages.assetId, assetUsages.contentId],
+          set: { published: true, updatedAt: new Date() },
+        });
+    });
+  }
+
+  /** Unpublishing revokes every asset this document was keeping public. */
+  async clearPublished(contentId: string): Promise<void> {
+    await this.db
+      .update(assetUsages)
+      .set({ published: false, updatedAt: new Date() })
+      .where(eq(assetUsages.contentId, contentId));
+  }
+
+  async deleteForContent(contentId: string): Promise<void> {
+    await this.db.delete(assetUsages).where(eq(assetUsages.contentId, contentId));
+  }
+
+  async count(): Promise<number> {
+    const rows = await this.db.select({ count: sql<number>`count(*)::int` }).from(assetUsages);
+    return rows[0]?.count ?? 0;
+  }
+
+  /**
+   * Every document with its draft and published field values, for the backfill.
+   *
+   * References are derived from field-type definitions rather than stored, so the
+   * backfill cannot be a SQL migration — it has to run inside the application.
+   */
+  async backfillSource(): Promise<
+    Array<{
+      id: string;
+      spaceId: string;
+      typeId: string;
+      draftFields: Record<string, unknown>;
+      publishedFields: Record<string, unknown> | null;
+    }>
+  > {
+    const rows = await this.db
+      .select({
+        id: contents.id,
+        spaceId: contents.spaceId,
+        typeId: contents.typeId,
+        draftFields: contents.fields,
+        publishedFields: publishedContents.fields,
+      })
+      .from(contents)
+      .leftJoin(publishedContents, eq(publishedContents.id, contents.id));
+
+    return rows.map((row) => ({
+      id: row.id,
+      spaceId: row.spaceId,
+      typeId: row.typeId,
+      draftFields: row.draftFields as Record<string, unknown>,
+      publishedFields: (row.publishedFields as Record<string, unknown> | null) ?? null,
+    }));
+  }
+}