@arki/journal 0.0.0-stage → 0.1.0

package/dist/storage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The entity row and stored values: load and save the row, exact-id checks, value
+ * comparison, the JSON round-trip check, freezing, and the root-database guard.
+ * Imports only leaf files (`types`, `errors`). Must not import `journal`, `api`,
+ * `write`, `command`, `history` or `worker`.
+ */
+import type { z } from 'zod';
+import type { AnyEntity, AnyEventDef, DbHandle, EntityDef, EntityId, EntityTable, ReducerRow, RootDb, Row } from './types.js';
+/** A select row has every column of its table. The check is real; the guard narrows. */
+export declare function isRowOf<Tbl extends EntityTable>(table: Tbl, value: object): value is Row<Tbl>;
+type EntityRowSource = Pick<AnyEntity, 'table' | 'keyColumn'>;
+export declare function loadRow(db: DbHandle, entity: EntityRowSource, id: string, lock: boolean): Promise<object | null>;
+/**
+ * With no row to compare against (a create and delete in one write, a replay of a missing row),
+ * `assertStoredId` sees nothing, so the id is checked up front, before any database access: not
+ * empty, within the key's length limit in code points (the column or the log would cut it), and,
+ * for a `uuid` key, lower-case and hyphenated.
+ */
+export declare function assertExactId(entity: Pick<AnyEntity, 'kind' | 'uuidKey' | 'keyLimit'>, id: string): void;
+export declare function assertStoredId(entity: Pick<AnyEntity, 'kind' | 'key'>, row: object | null, id: string): void;
+/** Insert, update or delete the row so it matches `next`. Returns the stored row. */
+export declare function saveReplayed<Tbl extends EntityTable, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, AnyEventDef, unknown, Key>, id: EntityId<Tbl, Key>, current: object | null, next: ReducerRow<Tbl, Key> | null): Promise<Row<Tbl> | null>;
+export declare function toRecord(value: object): Record<string, unknown>;
+export declare function showValue(value: unknown): string;
+/**
+ * The row the database returned must hold, for each of `columns`, the value the reducers produced.
+ * Replay recomputes from reducer output, so a value the database rounds, trims or alters would make
+ * replay and the table drift apart. Uses the same comparison as `verify`.
+ */
+export declare function assertStoredValues(entity: Pick<AnyEntity, 'kind'>, id: string, produced: object, saved: object, columns: Iterable<string>): void;
+/**
+ * Freeze a plain object or array and everything inside it. A `Date` is frozen
+ * itself; its internals are not touched. Anything else is left alone.
+ */
+export declare function deepFreeze<T>(value: T): T;
+/**
+ * Deep equality for stored rows: `verify` compares what replay produced with what the table holds.
+ * Strict: primitives, `Date`, value objects, arrays and plain objects only. A value object is a class
+ * instance with an `equals` method, such as a Temporal value from a custom column: it equals another
+ * instance of the same class when its `equals` says so. A `Map`, `Set`, other class instance or typed
+ * array is never equal to anything, because JSON storage would lose its contents.
+ */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * Throws `UNSTABLE_SCHEMA` unless the value survives JSON storage and a second parse
+ * unchanged. Replay depends on this. A value JSON cannot encode (a `bigint`, a cycle)
+ * is the same failure, with the serializer's error as `cause`.
+ */
+export declare function assertRoundTrips(schema: z.ZodType, value: unknown, kind: string, id: string, what: string): void;
+export declare function assertRootDb(db: RootDb, verb: string): void;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,UAAU,EACV,MAAM,EACN,GAAG,EACJ,MAAM,YAAY,CAAC;AAGpB,wFAAwF;AACxF,wBAAgB,OAAO,CAAC,GAAG,SAAS,WAAW,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,GAAG,CAAC,CAE7F;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC,CAAC;AAE9D,wBAAsB,OAAO,CAC3B,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAuBxG;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAW5G;AAED,qFAAqF;AACrF,wBAAsB,YAAY,CAAC,GAAG,SAAS,WAAW,EAAE,GAAG,SAAS,MAAM,EAC5E,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,EACzD,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,EACtB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,GAChC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAe1B;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE/D;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWhD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAC/B,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GACxB,IAAI,CAaN;AAoBD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAWzC;AAYD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAQzD;AAwBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBhH;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAM3D"}

package/dist/storage.js

@@ -0,0 +1,221 @@
+import { eq, getTableColumns, is } from 'drizzle-orm';
+import { PgAsyncTransaction } from 'drizzle-orm/pg-core';
+import { JournalError } from './errors.js';
+/** A select row has every column of its table. The check is real; the guard narrows. */
+export function isRowOf(table, value) {
+    return Object.keys(getTableColumns(table)).every(column => column in value);
+}
+export async function loadRow(db, entity, id, lock) {
+    const query = db.select().from(entity.table).where(eq(entity.keyColumn, id)).limit(1);
+    const rows = lock ? await query.for('update') : await query;
+    return rows[0] ?? null;
+}
+/**
+ * The id the caller passes must be exactly the key the database stores. A database can treat
+ * two spellings as one key (a `uuid` ignores case), but the log is keyed by the raw string,
+ * so a second spelling would split one entity's history in two.
+ */
+const CANONICAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * With no row to compare against (a create and delete in one write, a replay of a missing row),
+ * `assertStoredId` sees nothing, so the id is checked up front, before any database access: not
+ * empty, within the key's length limit in code points (the column or the log would cut it), and,
+ * for a `uuid` key, lower-case and hyphenated.
+ */
+export function assertExactId(entity, id) {
+    const fail = (reason) => {
+        throw new JournalError('ID_MISMATCH', entity.kind, id, reason);
+    };
+    if (id === '')
+        fail('the id is empty');
+    // (Surrogates are U+D800 to U+DFFF.) A lone surrogate is encoded by the driver as U+FFFD, so it would reach the history of another id.
+    // Iterating by code point yields a paired surrogate as one astral character, never as a surrogate.
+    for (const ch of id) {
+        const point = ch.codePointAt(0) ?? 0;
+        if (point >= 55_296 && point <= 57_343) {
+            fail('the id contains an unpaired surrogate, so it is not well-formed text and the database would store a different key');
+        }
+    }
+    const length = [...id].length;
+    if (length > entity.keyLimit.max) {
+        const owner = entity.keyLimit.source === 'column' ? "the key column's" : "the journal's";
+        fail(`the id is ${length} characters but the limit is ${entity.keyLimit.max}, ${owner} limit`);
+    }
+    if (entity.uuidKey && !CANONICAL_UUID.test(id)) {
+        fail(`${JSON.stringify(id)} is not a canonical uuid; uuid keys must be lower-case and hyphenated`);
+    }
+}
+export function assertStoredId(entity, row, id) {
+    if (row === null)
+        return;
+    const stored = Reflect.get(row, entity.key);
+    if (stored !== id) {
+        throw new JournalError('ID_MISMATCH', entity.kind, id, `the stored key is ${JSON.stringify(stored)} but the id given is ${JSON.stringify(id)}; use the stored form`);
+    }
+}
+/** Insert, update or delete the row so it matches `next`. Returns the stored row. */
+export async function saveReplayed(db, entity, id, current, next) {
+    const erased = entity.table;
+    if (next === null) {
+        if (current !== null)
+            await db.delete(erased).where(eq(entity.keyColumn, id));
+        return null;
+    }
+    const saved = current === null
+        ? await db.insert(erased).values(next).returning()
+        : await db.update(erased).set(next).where(eq(entity.keyColumn, id)).returning();
+    const row = saved[0];
+    if (row === undefined || !isRowOf(entity.table, row)) {
+        throw new Error(`journal: saving ${id} returned no complete row`);
+    }
+    return row;
+}
+export function toRecord(value) {
+    return { ...value };
+}
+export function showValue(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString();
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    if (typeof value === 'object' && value !== null) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return Object.prototype.toString.call(value);
+        }
+    }
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+/**
+ * The row the database returned must hold, for each of `columns`, the value the reducers produced.
+ * Replay recomputes from reducer output, so a value the database rounds, trims or alters would make
+ * replay and the table drift apart. Uses the same comparison as `verify`.
+ */
+export function assertStoredValues(entity, id, produced, saved, columns) {
+    const want = toRecord(produced);
+    const have = toRecord(saved);
+    for (const column of columns) {
+        if (!sameValue(want[column], have[column])) {
+            throw new JournalError('VALUE_MISMATCH', entity.kind, id, `column "${column}": the reducer produced ${showValue(want[column])} but the database stored ${showValue(have[column])}`);
+        }
+    }
+}
+/** Same own enumerable keys and same values. A key holding `undefined` is the same as a missing key, as in JSON. */
+function sameKeys(left, right, same) {
+    const keys = Object.keys(left).filter(key => left[key] !== undefined);
+    const rightKeys = Object.keys(right).filter(key => right[key] !== undefined);
+    return keys.length === rightKeys.length && keys.every(key => same(left[key], right[key]));
+}
+/** An object literal shape: prototype `Object.prototype` or `null`. A `Set`, `Map`, `Date` or class instance is not one. */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Freeze a plain object or array and everything inside it. A `Date` is frozen
+ * itself; its internals are not touched. Anything else is left alone.
+ */
+export function deepFreeze(value) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreeze(item);
+        Object.freeze(value);
+    }
+    else if (isPlainObject(value)) {
+        for (const item of Object.values(value))
+            deepFreeze(item);
+        Object.freeze(value);
+    }
+    else if (value instanceof Date) {
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Same length, and every index from 0 up compared. A hole is not equal to a value, `null` and `undefined` included. */
+function sameArray(a, b, same) {
+    if (a.length !== b.length)
+        return false;
+    for (let index = 0; index < a.length; index++) {
+        if (index in a !== index in b)
+            return false;
+        if (!same(a[index], b[index]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Deep equality for stored rows: `verify` compares what replay produced with what the table holds.
+ * Strict: primitives, `Date`, value objects, arrays and plain objects only. A value object is a class
+ * instance with an `equals` method, such as a Temporal value from a custom column: it equals another
+ * instance of the same class when its `equals` says so. A `Map`, `Set`, other class instance or typed
+ * array is never equal to anything, because JSON storage would lose its contents.
+ */
+export function sameValue(a, b) {
+    if (typeof a === 'function' || typeof a === 'symbol')
+        return false;
+    if (typeof a !== 'object' || a === null)
+        return Object.is(a, b);
+    if (a instanceof Date)
+        return b instanceof Date && a.getTime() === b.getTime();
+    if (Array.isArray(a))
+        return Array.isArray(b) && sameArray(a, b, sameValue);
+    if (isValueObject(a))
+        return Object.getPrototypeOf(a) === Object.getPrototypeOf(b) && a.equals(b) === true;
+    if (isPlainObject(a) && isPlainObject(b))
+        return sameKeys(a, b, sameValue);
+    return false;
+}
+/**
+ * A class instance that defines its own equality, like Temporal's `Instant` or `PlainDate`. A column
+ * whose driver rebuilds the same class on read round-trips it; a lossy column hands back another type
+ * or another value, and `equals` then reports the difference.
+ */
+function isValueObject(value) {
+    return !isPlainObject(value) && 'equals' in value && typeof value.equals === 'function';
+}
+/**
+ * Deep equality for a value that must survive JSON storage: primitives, arrays and
+ * plain objects only. A `Set` has no enumerable keys and would otherwise equal `{}`.
+ */
+function sameJson(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return sameArray(a, b, sameJson);
+    }
+    if (isPlainObject(a) && isPlainObject(b))
+        return sameKeys(a, b, sameJson);
+    return false;
+}
+/**
+ * Throws `UNSTABLE_SCHEMA` unless the value survives JSON storage and a second parse
+ * unchanged. Replay depends on this. A value JSON cannot encode (a `bigint`, a cycle)
+ * is the same failure, with the serializer's error as `cause`.
+ */
+export function assertRoundTrips(schema, value, kind, id, what) {
+    let stable;
+    try {
+        // Not structuredClone: the point is what JSON storage does to the value (Dates become strings).
+        const text = JSON.stringify(value);
+        const stored = JSON.parse(text);
+        const again = schema.safeParse(stored);
+        stable = again.success && sameJson(again.data, value);
+    }
+    catch (error) {
+        throw new JournalError('UNSTABLE_SCHEMA', kind, id, `${what}: the value cannot be stored as JSON`, {
+            cause: error,
+        });
+    }
+    if (!stable)
+        throw new JournalError('UNSTABLE_SCHEMA', kind, id, `${what}: the schema must accept its own stored output unchanged`);
+}
+export function assertRootDb(db, verb) {
+    if (is(db, PgAsyncTransaction)) {
+        throw new Error(`journal: ${verb} needs the root database, not a transaction: effects would run before the outer transaction commits`);
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

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

package/dist/testing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Test helper: an in-memory PGlite with a schema pushed, the fixture every
+ * journal test rebuilds by hand. `@electric-sql/pglite` and `drizzle-kit` are
+ * optional peers. Import this module only from tests. This is the one file
+ * that may import them.
+ */
+import { PGlite } from '@electric-sql/pglite';
+/**
+ * Open a fresh in-memory database with `schema` (the journal tables and the
+ * app's tables) pushed. Returns the Drizzle database and the PGlite client;
+ * call `client.close()` when the test file ends.
+ */
+export declare function openJournalDb(schema: Record<string, unknown>): Promise<{
+    db: import("drizzle-orm/pglite").PgliteDatabase<import("drizzle-orm").EmptyRelations> & {
+        $client: PGlite;
+    };
+    client: PGlite;
+}>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAI9C;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;GAOlE"}

package/dist/testing.js

@@ -0,0 +1,23 @@
+/**
+ * Test helper: an in-memory PGlite with a schema pushed, the fixture every
+ * journal test rebuilds by hand. `@electric-sql/pglite` and `drizzle-kit` are
+ * optional peers. Import this module only from tests. This is the one file
+ * that may import them.
+ */
+import { PGlite } from '@electric-sql/pglite';
+import { pushSchema } from 'drizzle-kit/api-postgres';
+import { drizzle } from 'drizzle-orm/pglite';
+/**
+ * Open a fresh in-memory database with `schema` (the journal tables and the
+ * app's tables) pushed. Returns the Drizzle database and the PGlite client;
+ * call `client.close()` when the test file ends.
+ */
+export async function openJournalDb(schema) {
+    const client = new PGlite('memory://');
+    await client.waitReady;
+    const db = drizzle({ client });
+    const { apply } = await pushSchema(schema, db);
+    await apply();
+    return { db, client };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAA+B;IACjE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,MAAM,CAAC,SAAS,CAAC;IACvB,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/C,MAAM,KAAK,EAAE,CAAC;IACd,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AACxB,CAAC"}

package/dist/transaction-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function oneAtATime<T>(handle: object, what: string, work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=transaction-guard.d.ts.map

package/dist/transaction-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-guard.d.ts","sourceRoot":"","sources":["../src/transaction-guard.ts"],"names":[],"mappings":"AA0BA,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc9F"}

package/dist/transaction-guard.js

@@ -0,0 +1,39 @@
+/**
+ * The guard that allows one journal operation per transaction at a time.
+ * Its `WeakMap` is the only module-level state in the library, and it must stay
+ * module-scoped: see the comment on it.
+ * Imports nothing from this package. `write` and `command` import it.
+ */
+import { is } from 'drizzle-orm';
+import { PgAsyncTransaction } from 'drizzle-orm/pg-core';
+/** Passed to `then` twice: waits for a promise to settle, whether it resolves or rejects. */
+const ignoreSettlement = () => undefined;
+/**
+ * Savepoints are a stack. Two journal operations open on one transaction at the
+ * same time release each other's savepoint, so a caught failure of one could
+ * erase what the other wrote. A transaction therefore holds one operation at a
+ * time. A second one is refused: it waits for the first to settle (so the
+ * caller's rollback undoes it whole), then rejects. A child runs on its own
+ * savepoint handle, so nesting is fine. The root database opens a separate
+ * transaction per operation and is never busy.
+ *
+ * The map is module-scoped on purpose. Two journals can run on one transaction,
+ * and then they share its savepoint stack, so they must share this guard too.
+ * Do not move it into the journal factory.
+ */
+const inFlight = new WeakMap();
+export function oneAtATime(handle, what, work) {
+    if (!is(handle, PgAsyncTransaction))
+        return work();
+    const busy = inFlight.get(handle);
+    if (busy !== undefined) {
+        return busy.then(ignoreSettlement, ignoreSettlement).then(() => {
+            throw new Error(`journal: ${what} started on a transaction that already has a journal operation in flight; await operations on one transaction one at a time`);
+        });
+    }
+    // eslint-disable-next-line drizzle/enforce-delete-with-where -- WeakMap#delete, not a Drizzle query
+    const running = work().finally(() => inFlight.delete(handle));
+    inFlight.set(handle, running);
+    return running;
+}
+//# sourceMappingURL=transaction-guard.js.map

package/dist/transaction-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-guard.js","sourceRoot":"","sources":["../src/transaction-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,6FAA6F;AAC7F,MAAM,gBAAgB,GAAG,GAAc,EAAE,CAAC,SAAS,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA4B,CAAC;AACzD,MAAM,UAAU,UAAU,CAAI,MAAc,EAAE,IAAY,EAAE,IAAsB;IAChF,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC;QAAE,OAAO,IAAI,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAC7D,MAAM,IAAI,KAAK,CACb,YAAY,IAAI,6HAA6H,CAC9I,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IACD,oGAAoG;IACpG,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC"}