@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/esm/database/pagination.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { ValidationError } from '../common/errors.js';
+import { buildCursorPageMeta } from '../common/response.js';
+import { zodIssuesToErrors } from '../validation/index.js';
+/**
+ * Cursor (keyset) pagination (D6). Clients send `?cursor=&limit=`; the cursor is an opaque
+ * base64url token of `{ sortKey, id }` (the last row's sort value plus an id tie-breaker).
+ * Dependency-light: usable from controllers without the database subpath.
+ */
+/** Largest page size a client may ask for. */
+export const MAX_PAGE_LIMIT = 100;
+/** Page size when the client sends none. */
+export const DEFAULT_PAGE_LIMIT = 20;
+const MAX_CURSOR_LENGTH = 512;
+/** `{ cursor?, limit }` query schema: limit 1–100, default 20; unknown keys are stripped. */
+export const cursorQuerySchema = z.object({
+    cursor: z.string().trim().min(1).max(MAX_CURSOR_LENGTH).optional(),
+    limit: z.coerce.number().int().min(1).max(MAX_PAGE_LIMIT).default(DEFAULT_PAGE_LIMIT),
+});
+/**
+ * Validates `{ cursor, limit }` from a query string.
+ *
+ * @throws ValidationError (422) with field errors when invalid.
+ * @example const { cursor, limit } = parseCursorQuery(req.query);
+ */
+export function parseCursorQuery(input) {
+    const result = cursorQuerySchema.safeParse({ cursor: emptyToUndefined(input?.cursor), limit: emptyToUndefined(input?.limit) });
+    if (result.success)
+        return result.data;
+    throw new ValidationError(zodIssuesToErrors(result.error), 'Invalid pagination parameters');
+}
+function emptyToUndefined(value) {
+    return value === '' || value === null ? undefined : value;
+}
+/**
+ * Encodes a cursor. Date sort keys become ISO strings.
+ *
+ * @example encodeCursor({ sortKey: row.createdAt, id: row.id })
+ */
+export function encodeCursor(cursor) {
+    const sortKey = cursor.sortKey instanceof Date ? cursor.sortKey.toISOString() : cursor.sortKey;
+    return Buffer.from(JSON.stringify({ k: sortKey, i: cursor.id }), 'utf8').toString('base64url');
+}
+/**
+ * Decodes a cursor produced by {@link encodeCursor}.
+ *
+ * @throws ValidationError (422, field `cursor`) for anything malformed or tampered with.
+ */
+export function decodeCursor(token) {
+    const invalid = () => new ValidationError({ cursor: ['Invalid cursor'] }, 'Invalid cursor');
+    if (typeof token !== 'string' || token.length === 0 || token.length > MAX_CURSOR_LENGTH || !/^[A-Za-z0-9_-]+$/.test(token))
+        throw invalid();
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw invalid();
+    }
+    if (!parsed || typeof parsed !== 'object')
+        throw invalid();
+    const { k, i } = parsed;
+    const validKey = k === null || typeof k === 'string' || (typeof k === 'number' && Number.isFinite(k));
+    if (!validKey || typeof i !== 'string' || i.length === 0 || i.length > 64)
+        throw invalid();
+    return { sortKey: k, id: i };
+}
+/**
+ * Builds a page from `limit + 1` fetched rows: the extra row only signals that more exist.
+ *
+ * @param rows Rows fetched with `limit + 1`.
+ * @param limit The page size.
+ * @param cursorOf Extracts `{ sortKey, id }` from a row for the next cursor.
+ */
+export function buildCursorPage(rows, limit, cursorOf) {
+    const data = rows.slice(0, limit);
+    const hasMore = rows.length > limit && data.length > 0;
+    const nextCursor = hasMore ? encodeCursor(cursorOf(data[data.length - 1])) : null;
+    return { data, meta: buildCursorPageMeta(limit, nextCursor) };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/esm/database/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/database/pagination.ts"],"names":[],"mappings":"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"}

package/dist/esm/database/pool.js

@@ -0,0 +1,51 @@
+import mysql from 'mysql2/promise';
+/**
+ * mysql2 pool for Drizzle. Sessions run in UTC and utf8mb4 so timestamps and emoji round-trip
+ * unchanged regardless of server defaults.
+ */
+export function createMysqlPool(options) {
+    return mysql.createPool({
+        host: options.host,
+        port: options.port,
+        user: options.user,
+        password: options.password,
+        database: options.database,
+        connectionLimit: options.poolMax ?? 10,
+        waitForConnections: true,
+        enableKeepAlive: true,
+        timezone: '+00:00',
+        charset: 'utf8mb4_unicode_ci',
+        dateStrings: false,
+        supportBigNumbers: true,
+    });
+}
+/**
+ * Knex config for migrations and seeds: mysql2, utf8mb4, UTC, `.cjs` files only. Services call it
+ * through `knexConfig(env)` in their `knexfile.js`.
+ */
+export function createKnexConfig(options) {
+    return {
+        client: 'mysql2',
+        connection: {
+            host: options.host,
+            port: options.port,
+            user: options.user,
+            password: options.password,
+            database: options.database,
+            timezone: '+00:00',
+            charset: 'utf8mb4',
+        },
+        pool: { min: 0, max: options.poolMax ?? 10 },
+        migrations: { directory: options.migrationsDir ?? './migrations', tableName: 'knex_migrations', extension: 'cjs', loadExtensions: ['.cjs'] },
+        seeds: { directory: options.seedsDir ?? './seeds', extension: 'cjs', loadExtensions: ['.cjs'] },
+    };
+}
+/** Readiness probe helper. */
+export async function pingMysql(pool) {
+    await pool.query('SELECT 1');
+}
+/** Escapes `%`, `_` and `\` for use inside a LIKE pattern. */
+export function escapeLike(value) {
+    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+//# sourceMappingURL=pool.js.map

package/dist/esm/database/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../../src/database/pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,gBAAgB,CAAC;AA0BnC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,OAAO,KAAK,CAAC,UAAU,CAAC;QACtB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,eAAe,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;QACtC,kBAAkB,EAAE,IAAI;QACxB,eAAe,EAAE,IAAI;QACrB,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,oBAAoB;QAC7B,WAAW,EAAE,KAAK;QAClB,iBAAiB,EAAE,IAAI;KACxB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,OAAO;QACL,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE;YACV,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,SAAS;SACnB;QACD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE;QAC5C,UAAU,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,IAAI,cAAc,EAAE,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,MAAM,CAAC,EAAE;QAC5I,KAAK,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,QAAQ,IAAI,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,MAAM,CAAC,EAAE;KAChG,CAAC;AACJ,CAAC;AAED,8BAA8B;AAC9B,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAgB;IAC9C,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AAC/B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACrD,CAAC"}

package/dist/esm/database/scoped-repository.js

@@ -0,0 +1,128 @@
+import { and, asc, count, desc, eq, gt, lt, or } from 'drizzle-orm';
+import { ForbiddenError } from '../common/errors.js';
+import { buildCursorPage, decodeCursor, DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from './pagination.js';
+import { resolveColumn } from './scopes.js';
+/**
+ * Base for every repository over scoped data (Drizzle). Every read, count, update and delete is
+ * AND-ed with the scope's condition, and every insert is stamped with the scope value; there is no
+ * method that returns an unscoped query. Subclasses add queries only through {@link scoped} and
+ * {@link executor}.
+ *
+ * @example
+ * class NoteRepository extends ScopedRepository<typeof notes, ScopeContext<'workspaceId'>> {
+ *   findByTitle(ctx: ScopeContext<'workspaceId'>, title: string) {
+ *     return this.executor().select().from(this.table).where(this.scoped(ctx, eq(this.table.title, title)));
+ *   }
+ * }
+ * const repo = new NoteRepository(db, notes, workspaceScope);
+ */
+export class ScopedRepository {
+    #db;
+    table;
+    scope;
+    idColumn;
+    constructor(db, table, scope, options = {}) {
+        this.#db = db;
+        this.table = table;
+        this.scope = scope;
+        this.idColumn = resolveColumn(table, options.idColumn ?? 'id').column;
+        resolveColumn(table, scope.column); // fail fast when the table lacks the scope column
+    }
+    /** The row with `id` inside the caller's scope, or null (absent and out-of-scope look the same). */
+    async findById(ctx, id, options = {}) {
+        const rows = await this.executor(options.tx).select().from(this.table)
+            .where(this.scoped(ctx, eq(this.idColumn, id))).limit(1);
+        return rows[0] ?? null;
+    }
+    /** Rows inside the caller's scope, keyset-paginated by `orderBy` then id. */
+    async findMany(ctx, options = {}) {
+        return this.selectPage(ctx, options, clampLimit(options.limit));
+    }
+    /** Like {@link findMany}, returning `{ data, meta: { limit, nextCursor, hasMore } }`. */
+    async findPage(ctx, options = {}) {
+        const limit = clampLimit(options.limit);
+        const rows = await this.selectPage(ctx, options, limit + 1);
+        const { key: sortKey } = resolveColumn(this.table, options.orderBy?.column ?? this.idColumn.name);
+        const { key: idKey } = resolveColumn(this.table, this.idColumn.name);
+        return buildCursorPage(rows, limit, (row) => {
+            const record = row;
+            return { sortKey: record[sortKey], id: String(record[idKey]) };
+        });
+    }
+    /** Number of rows inside the caller's scope matching `where`. */
+    async count(ctx, where, options = {}) {
+        const rows = await this.executor(options.tx).select({ n: count() }).from(this.table).where(this.scoped(ctx, where));
+        return Number(rows[0]?.n ?? 0);
+    }
+    /**
+     * Inserts rows stamped with the caller's scope value.
+     *
+     * @throws ForbiddenError (`SCOPE_MISMATCH`) when a row names another scope.
+     * @returns The stamped rows as written.
+     */
+    async insert(ctx, rows, options = {}) {
+        const list = (Array.isArray(rows) ? rows : [rows]).map((row) => this.scope.stamp(this.table, row, ctx));
+        if (list.length === 0)
+            return [];
+        await this.executor(options.tx).insert(this.table).values(list);
+        return list;
+    }
+    /**
+     * Updates rows inside the caller's scope. Rows never move between scopes.
+     *
+     * @throws ForbiddenError (`SCOPE_IMMUTABLE`) when `values` sets the scope column.
+     * @returns Number of rows changed.
+     */
+    async update(ctx, where, values, options = {}) {
+        if (resolveColumn(this.table, this.scope.column).key in values) {
+            throw new ForbiddenError(`The ${this.scope.name} of a row cannot be changed`, { code: 'SCOPE_IMMUTABLE' });
+        }
+        const result = await this.executor(options.tx).update(this.table).set(values).where(this.scoped(ctx, where));
+        return affectedRows(result);
+    }
+    /**
+     * Deletes rows inside the caller's scope.
+     *
+     * @returns Number of rows deleted.
+     */
+    async delete(ctx, where, options = {}) {
+        const result = await this.executor(options.tx).delete(this.table).where(this.scoped(ctx, where));
+        return affectedRows(result);
+    }
+    /** The scope condition AND-ed with `conditions`. The only way subclasses may build a WHERE. */
+    scoped(ctx, ...conditions) {
+        return and(this.scope.condition(this.table, ctx), ...conditions);
+    }
+    /** The executor for a call: `tx` when given, otherwise the pool. Always pair with {@link scoped}. */
+    executor(tx) {
+        return tx ?? this.#db;
+    }
+    async selectPage(ctx, options, take) {
+        const sort = resolveColumn(this.table, options.orderBy?.column ?? this.idColumn.name).column;
+        const descending = (options.orderBy?.direction ?? 'desc') === 'desc';
+        const after = options.cursor ? this.afterCursor(options.cursor, sort, descending) : undefined;
+        const order = descending ? [desc(sort), desc(this.idColumn)] : [asc(sort), asc(this.idColumn)];
+        const rows = await this.executor(options.tx).select().from(this.table)
+            .where(this.scoped(ctx, options.where, after)).orderBy(...order).limit(take);
+        return rows;
+    }
+    /** Keyset condition: rows strictly after the cursor's (sortKey, id) in the sort direction. */
+    afterCursor(token, sort, descending) {
+        const { sortKey, id } = decodeCursor(token);
+        const past = descending ? lt : gt;
+        if (sort === this.idColumn)
+            return past(this.idColumn, id);
+        const value = sort.dataType === 'date' && typeof sortKey === 'string' ? new Date(sortKey) : sortKey;
+        return or(past(sort, value), and(eq(sort, value), past(this.idColumn, id)));
+    }
+}
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return DEFAULT_PAGE_LIMIT;
+    return Math.min(MAX_PAGE_LIMIT, Math.max(1, Math.trunc(limit)));
+}
+function affectedRows(result) {
+    const header = (Array.isArray(result) ? result[0] : result);
+    return Number(header?.affectedRows ?? 0);
+}
+//# sourceMappingURL=scoped-repository.js.map

package/dist/esm/database/scoped-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-repository.js","sourceRoot":"","sources":["../../../src/database/scoped-repository.ts"],"names":[],"mappings":"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"}

package/dist/esm/database/scopes.js

@@ -0,0 +1,157 @@
+import { eq, getTableColumns, isNotNull } from 'drizzle-orm';
+import { ForbiddenError } from '../common/errors.js';
+/**
+ * Finds a table column by its database name.
+ *
+ * @throws Error when the table has no such column (a wiring bug, caught at startup or in tests).
+ */
+export function resolveColumn(table, dbName) {
+    const columns = getTableColumns(table);
+    for (const [key, column] of Object.entries(columns)) {
+        if (column.name === dbName)
+            return { key, column };
+    }
+    throw new Error(`Table has no column "${dbName}"`);
+}
+function requireValue(value, scopeName, code) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ForbiddenError(`A ${scopeName} scope is required`, { code });
+    }
+    return value;
+}
+/** Sets `column` on `row` to `value`; refuses a row that carries a different value. */
+function stampColumn(table, row, dbName, value, scopeName) {
+    const { key } = resolveColumn(table, dbName);
+    const current = row[key];
+    if (current !== undefined && current !== null && current !== value) {
+        throw new ForbiddenError(`Row belongs to another ${scopeName}`, { code: 'SCOPE_MISMATCH' });
+    }
+    return { ...row, [key]: value };
+}
+/**
+ * Defines a scope whose value comes from the request context (the gateway-signed identity, never a
+ * request body).
+ *
+ * @example const workspaceScope = defineScope({ name: 'workspace', column: 'workspace_id', contextKey: 'workspaceId' });
+ */
+export function defineScope(options) {
+    const { name, column, contextKey } = options;
+    const valueOf = (ctx) => requireValue(ctx?.[contextKey], name, 'SCOPE_REQUIRED');
+    return Object.freeze({
+        name,
+        column,
+        contextKey,
+        valueOf,
+        condition: (table, ctx) => eq(resolveColumn(table, column).column, valueOf(ctx)),
+        stamp: (table, row, ctx) => stampColumn(table, row, column, valueOf(ctx), name),
+    });
+}
+/**
+ * Rows owned by one principal (e.g. a user's own records). Refuses a missing owner id, so an
+ * anonymous call can never fall through to "all owners".
+ *
+ * @example const ownerScope = new OwnerScope({ name: 'owner', column: 'user_id' });
+ */
+export class OwnerScope {
+    /** Readable name (e.g. `owner`). */
+    name;
+    /** Database name of the owner column (e.g. `user_id`). */
+    column;
+    /** @param options `name` for messages, `column` = database name of the owner column. */
+    constructor(options) {
+        this.name = options.name;
+        this.column = options.column;
+    }
+    /** The owner id from `ctx`; throws ForbiddenError (`OWNER_REQUIRED`) when it is missing. */
+    ownerIdOf(ctx) {
+        return requireValue(ctx?.ownerId, this.name, 'OWNER_REQUIRED');
+    }
+    /** `owner column = ownerId`. @throws ForbiddenError (`OWNER_REQUIRED`) without an owner id. */
+    condition(table, ctx) {
+        return eq(resolveColumn(table, this.column).column, this.ownerIdOf(ctx));
+    }
+    /** Sets the owner column. @throws ForbiddenError (`OWNER_REQUIRED`, `SCOPE_MISMATCH`). */
+    stamp(table, row, ctx) {
+        return stampColumn(table, row, this.column, this.ownerIdOf(ctx), this.name);
+    }
+}
+const ISSUE = Symbol('PlatformScope.issue');
+/**
+ * Proof that an identity may act across scopes. Only {@link PlatformScopeDefinition.authorize} can
+ * create one, and only when the definition's predicate approves the identity.
+ */
+export class PlatformScope {
+    #definition;
+    /** @internal Use `definePlatformScope(...).authorize(identity)`. */
+    constructor(token, definition) {
+        if (token !== ISSUE)
+            throw new ForbiddenError('Platform scope must be authorized', { code: 'PLATFORM_SCOPE_REQUIRED' });
+        this.#definition = definition;
+    }
+    /** True when this grant was issued by `definition`. */
+    issuedBy(definition) {
+        return this.#definition === definition;
+    }
+}
+/**
+ * Cross-scope access for platform operators. Rows of every scope are reachable, but the query still
+ * filters on the scope column (`IS NOT NULL`) and inserts must name their scope explicitly.
+ */
+export class PlatformScopeDefinition {
+    /** Readable name (e.g. `platform`). */
+    name;
+    /** Database name of the scope column the platform scope spans. */
+    column;
+    #predicate;
+    /** Prefer {@link definePlatformScope}. */
+    constructor(options) {
+        this.name = options.name;
+        this.column = options.column;
+        this.#predicate = options.predicate;
+    }
+    /**
+     * Issues a {@link PlatformScope} for `identity`.
+     *
+     * @throws ForbiddenError (`PLATFORM_SCOPE_DENIED`) when the predicate refuses (or throws).
+     */
+    authorize(identity) {
+        let allowed = false;
+        try {
+            allowed = identity != null && this.#predicate(identity);
+        }
+        catch {
+            allowed = false;
+        }
+        if (!allowed)
+            throw new ForbiddenError('Platform access is required', { code: 'PLATFORM_SCOPE_DENIED' });
+        return new PlatformScope(ISSUE, this);
+    }
+    /** `scope column IS NOT NULL`. @throws ForbiddenError (`PLATFORM_SCOPE_REQUIRED`) without a grant from this scope. */
+    condition(table, ctx) {
+        this.assertGrant(ctx);
+        return isNotNull(resolveColumn(table, this.column).column);
+    }
+    /** Requires the row to name its scope. @throws ForbiddenError (`PLATFORM_SCOPE_REQUIRED`, `SCOPE_REQUIRED`). */
+    stamp(table, row, ctx) {
+        this.assertGrant(ctx);
+        const { key } = resolveColumn(table, this.column);
+        requireValue(row[key], this.name, 'SCOPE_REQUIRED');
+        return row;
+    }
+    assertGrant(ctx) {
+        if (!(ctx instanceof PlatformScope) || !ctx.issuedBy(this)) {
+            throw new ForbiddenError('Platform access is required', { code: 'PLATFORM_SCOPE_REQUIRED' });
+        }
+    }
+}
+/**
+ * Defines the platform (cross-scope) scope.
+ *
+ * @example
+ * const platformScope = definePlatformScope({ name: 'platform', column: 'workspace_id', predicate: (u: AuthUser) => u.isSuperAdmin });
+ * const grant = platformScope.authorize(req.user); // throws 403 for anyone else
+ */
+export function definePlatformScope(options) {
+    return new PlatformScopeDefinition(options);
+}
+//# sourceMappingURL=scopes.js.map

package/dist/esm/database/scopes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../../src/database/scopes.ts"],"names":[],"mappings":"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"}

package/dist/esm/database/table-names.js

@@ -0,0 +1,11 @@
+/** Default name of the transactional outbox table. */
+export const DEFAULT_OUTBOX_TABLE = 'event_outbox';
+/** Default name of the consumer idempotency ledger. */
+export const DEFAULT_PROCESSED_EVENTS_TABLE = 'processed_events';
+/** Default name of the scheduled-job runs table. */
+export const DEFAULT_SCHEDULER_RUNS_TABLE = 'scheduler_runs';
+/** Scheduler run states, shared by the Drizzle table and the Knex helper. */
+export const SCHEDULER_RUN_STATUSES = ['running', 'succeeded', 'failed'];
+/** Logical exchanges an outbox row can target: topic events or direct commands. */
+export const OUTBOX_EXCHANGES = ['events', 'commands'];
+//# sourceMappingURL=table-names.js.map

package/dist/esm/database/table-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-names.js","sourceRoot":"","sources":["../../../src/database/table-names.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAC;AACnD,uDAAuD;AACvD,MAAM,CAAC,MAAM,8BAA8B,GAAG,kBAAkB,CAAC;AACjE,oDAAoD;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,gBAAgB,CAAC;AAC7D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAClF,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAU,CAAC"}

package/dist/esm/database/tables.js

@@ -0,0 +1,61 @@
+import { sql } from 'drizzle-orm';
+import { DEFAULT_OUTBOX_TABLE, DEFAULT_PROCESSED_EVENTS_TABLE, DEFAULT_SCHEDULER_RUNS_TABLE, OUTBOX_EXCHANGES, SCHEDULER_RUN_STATUSES } from './table-names.js';
+import { char, datetime, index, int, json, mysqlEnum, mysqlTable, uniqueIndex, varchar } from 'drizzle-orm/mysql-core';
+/**
+ * Drizzle definitions of the infrastructure tables every service may own. Each matches the Knex
+ * helper of the same name in `@heavybit/shared-lib/knex` (`outboxColumns`, `processedEventsColumns`,
+ * `schedulerRunsColumns`); a test keeps the two in step. Pass a custom name when a service needs one.
+ */
+const ms = (name) => datetime(name, { mode: 'date', fsp: 3 });
+const createdNow = (name) => ms(name).notNull().default(sql `CURRENT_TIMESTAMP(3)`);
+export { DEFAULT_OUTBOX_TABLE, DEFAULT_PROCESSED_EVENTS_TABLE, DEFAULT_SCHEDULER_RUNS_TABLE, OUTBOX_EXCHANGES, SCHEDULER_RUN_STATUSES };
+/** Transactional outbox (`event_outbox` by default): domain change and message in one transaction. */
+export function outboxTable(name = DEFAULT_OUTBOX_TABLE) {
+    return mysqlTable(name, {
+        id: char('id', { length: 26 }).primaryKey(),
+        routingKey: varchar('routing_key', { length: 191 }).notNull(),
+        /** Logical exchange: `events` (topic fan-out) or `commands` (direct, one owner). */
+        exchange: mysqlEnum('exchange', OUTBOX_EXCHANGES).notNull().default('events'),
+        payload: json('payload').notNull(),
+        /** Correlation id of the request that staged the row; the relay sends it as `x-correlation-id`. */
+        correlationId: varchar('correlation_id', { length: 64 }),
+        attempts: int('attempts', { unsigned: true }).notNull().default(0),
+        lastError: varchar('last_error', { length: 500 }),
+        createdAt: createdNow('created_at'),
+        publishedAt: ms('published_at'),
+    }, (t) => [index(`${name}_published_at_id_index`).on(t.publishedAt, t.id)]);
+}
+/** Consumer idempotency ledger: one row per (consumer, event id). */
+export function processedEventsTable(name = DEFAULT_PROCESSED_EVENTS_TABLE) {
+    return mysqlTable(name, {
+        id: char('id', { length: 26 }).primaryKey(),
+        consumer: varchar('consumer', { length: 191 }).notNull(),
+        eventId: varchar('event_id', { length: 64 }).notNull(),
+        processedAt: createdNow('processed_at'),
+    }, (t) => [
+        uniqueIndex(`${name}_consumer_event_id_unique`).on(t.consumer, t.eventId),
+        index(`${name}_processed_at_index`).on(t.processedAt),
+    ]);
+}
+/** Scheduled-job runs: one row per (job, run key), so a run is never executed twice. */
+export function schedulerRunsTable(name = DEFAULT_SCHEDULER_RUNS_TABLE) {
+    return mysqlTable(name, {
+        id: char('id', { length: 26 }).primaryKey(),
+        job: varchar('job', { length: 191 }).notNull(),
+        runKey: varchar('run_key', { length: 191 }).notNull(),
+        status: mysqlEnum('status', SCHEDULER_RUN_STATUSES).notNull().default('running'),
+        error: varchar('error', { length: 500 }),
+        startedAt: createdNow('started_at'),
+        finishedAt: ms('finished_at'),
+    }, (t) => [
+        uniqueIndex(`${name}_job_run_key_unique`).on(t.job, t.runKey),
+        index(`${name}_job_started_at_index`).on(t.job, t.startedAt),
+    ]);
+}
+/** `event_outbox` with the default name. */
+export const outbox = outboxTable();
+/** `processed_events` with the default name. */
+export const processedEvents = processedEventsTable();
+/** `scheduler_runs` with the default name. */
+export const schedulerRuns = schedulerRunsTable();
+//# sourceMappingURL=tables.js.map

package/dist/esm/database/tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.js","sourceRoot":"","sources":["../../../src/database/tables.ts"],"names":[],"mappings":"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"}