@cqrs-ddd/pipeline-idempotency 0.5.0

package/dist/stores/postgres.store.js

@@ -0,0 +1,187 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Allows `table` or `schema.table` made of unquoted SQL identifiers only. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function assertSafeTable(table) {
+    if (!SAFE_IDENTIFIER.test(table)) {
+        throw new Error(`Invalid idempotency table name "${table}". ` +
+            'Use an unquoted identifier like "idempotency_keys" or "schema.idempotency_keys".');
+    }
+    return table;
+}
+/**
+ * SQL that creates the idempotency table and its `expires_at` index. Run it
+ * from an application migration, not at request time.
+ *
+ * `response` holds the response as JSON text rather than `jsonb`: `jsonb`
+ * rejects the `\u0000` and unpaired-surrogate escapes `JSON.stringify` writes,
+ * and a completed response must always be storable and replay exactly.
+ *
+ * @param table - Table name (validated). Default `'idempotency_keys'`.
+ * @returns SQL statements required by {@link PostgresIdempotencyStore}.
+ */
+export function createIdempotencyTableSql(table = 'idempotency_keys') {
+    const name = assertSafeTable(table);
+    return `CREATE TABLE IF NOT EXISTS ${name} (
+  key           TEXT        PRIMARY KEY,
+  status        TEXT        NOT NULL,
+  request_name  TEXT        NOT NULL,
+  claim_id      TEXT,
+  fingerprint   TEXT,
+  replay_scope  TEXT,
+  response      TEXT,
+  created_at    TIMESTAMPTZ NOT NULL,
+  completed_at  TIMESTAMPTZ,
+  expires_at    TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ${indexName(name)} ON ${name} (expires_at);`;
+}
+/** Derives a safe index name from a (possibly schema-qualified) table name. */
+function indexName(table) {
+    const base = table.includes('.') ? table.split('.').pop() : table;
+    return `${base}_expires_at_idx`;
+}
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+function mapRow(key, row) {
+    return {
+        key,
+        status: row.status,
+        requestName: row.request_name,
+        claimId: row.claim_id ?? undefined,
+        fingerprint: row.fingerprint ?? undefined,
+        replayScope: row.replay_scope ?? undefined,
+        // SQL NULL: no response stored. The text 'null' is an explicit null response.
+        response: row.has_response
+            ? JSON.parse(row.response)
+            : undefined,
+        createdAt: toIso(row.created_at),
+        completedAt: row.completed_at ? toIso(row.completed_at) : undefined,
+    };
+}
+/**
+ * Validates a lease TTL before it is interpolated into a PostgreSQL interval.
+ *
+ * Lease expiry is computed and compared using the database clock. The returned
+ * string is safe to concatenate only because the input is first constrained to a
+ * positive safe integer.
+ */
+function assertLeaseTtl(ttlMs) {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+        throw new TypeError(`Idempotency lease TTL must be a positive safe integer in milliseconds, received ${ttlMs}.`);
+    }
+    return String(ttlMs);
+}
+/**
+ * {@link IdempotencyStore} backed by **Postgres** (`pg`) — a drop-in
+ * replacement that shares state across instances without a separate Redis.
+ *
+ * Create the table once with {@link createIdempotencyTableSql}. Atomicity of
+ * {@link setIfAbsent} comes from a conditional `INSERT … ON CONFLICT … DO
+ * UPDATE`: an absent key is inserted, an expired key is atomically replaced,
+ * and a live conflict is left untouched. Completion/release also compare
+ * `claim_id` in the same SQL statement, so a stale execution cannot mutate a
+ * newer claim. The table name is validated as a plain SQL identifier (it is
+ * interpolated, not parameterized); all values are passed as bound parameters.
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * await pool.query(createIdempotencyTableSql());
+ * const store = new PostgresIdempotencyStore(pool);
+ * ```
+ */
+export class PostgresIdempotencyStore {
+    db;
+    table;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.table = assertSafeTable(options.table ?? 'idempotency_keys');
+    }
+    async get(key) {
+        const result = await this.db.query(`SELECT status, request_name, claim_id, fingerprint, replay_scope, response,
+              response IS NOT NULL AS has_response,
+              created_at, completed_at
+         FROM ${this.table}
+        WHERE key = $1 AND expires_at > now()`, [key]);
+        const row = result.rows[0];
+        return row ? mapRow(key, row) : undefined;
+    }
+    async setIfAbsent(key, record, ttlMs) {
+        const result = await this.db.query(`INSERT INTO ${this.table} AS current_record
+         (key, status, request_name, claim_id, fingerprint, replay_scope, response, created_at, completed_at, expires_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, now() + ($10 || ' milliseconds')::interval)
+       ON CONFLICT (key) DO UPDATE SET
+         status = EXCLUDED.status,
+         request_name = EXCLUDED.request_name,
+         claim_id = EXCLUDED.claim_id,
+         fingerprint = EXCLUDED.fingerprint,
+         replay_scope = EXCLUDED.replay_scope,
+         response = EXCLUDED.response,
+         created_at = EXCLUDED.created_at,
+         completed_at = EXCLUDED.completed_at,
+         expires_at = EXCLUDED.expires_at
+       WHERE current_record.expires_at <= now()
+       RETURNING key`, [key, ...this.toValues(record, ttlMs)]);
+        return result.rows.length > 0;
+    }
+    async completeIfOwned(key, claimId, record, ttlMs) {
+        const result = await this.db.query(`UPDATE ${this.table}
+          SET status = $3,
+              request_name = $4,
+              claim_id = $5,
+              fingerprint = $6,
+              replay_scope = $7,
+              response = $8,
+              created_at = $9,
+              completed_at = $10,
+              expires_at = now() + ($11 || ' milliseconds')::interval
+        WHERE key = $1
+          AND claim_id = $2
+          AND status = 'in_progress'
+          AND expires_at > now()
+        RETURNING key`, [key, claimId, ...this.toValues(record, ttlMs)]);
+        return result.rows.length > 0;
+    }
+    async deleteIfOwned(key, claimId) {
+        const result = await this.db.query(`DELETE FROM ${this.table}
+        WHERE key = $1
+          AND claim_id = $2
+          AND expires_at > now()
+        RETURNING key`, [key, claimId]);
+        return result.rows.length > 0;
+    }
+    async set(key, record, ttlMs) {
+        await this.db.query(`INSERT INTO ${this.table}
+         (key, status, request_name, claim_id, fingerprint, replay_scope, response, created_at, completed_at, expires_at)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, now() + ($10 || ' milliseconds')::interval)
+       ON CONFLICT (key) DO UPDATE SET
+         status = EXCLUDED.status,
+         request_name = EXCLUDED.request_name,
+         claim_id = EXCLUDED.claim_id,
+         fingerprint = EXCLUDED.fingerprint,
+         replay_scope = EXCLUDED.replay_scope,
+         response = EXCLUDED.response,
+         created_at = EXCLUDED.created_at,
+         completed_at = EXCLUDED.completed_at,
+         expires_at = EXCLUDED.expires_at`, [key, ...this.toValues(record, ttlMs)]);
+    }
+    async delete(key) {
+        await this.db.query(`DELETE FROM ${this.table} WHERE key = $1`, [key]);
+    }
+    toValues(record, ttlMs) {
+        return [
+            record.status,
+            record.requestName,
+            record.claimId ?? null,
+            record.fingerprint ?? null,
+            record.replayScope ?? null,
+            record.response === undefined ? null : JSON.stringify(record.response),
+            record.createdAt,
+            record.completedAt ?? null,
+            assertLeaseTtl(ttlMs),
+        ];
+    }
+}
+//# sourceMappingURL=postgres.store.js.map

package/dist/stores/postgres.store.js.map

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

package/dist/stores/redis.store.d.ts

@@ -0,0 +1,62 @@
+import type { IdempotencyRecord } from '../interfaces/idempotency-record.interface.js';
+import type { IdempotencyStore } from '../interfaces/idempotency-store.interface.js';
+/**
+ * Minimal structural shape of a node-redis client (`redis` v4 or later). Declared
+ * locally so this package does not hard-depend on `redis` — a real client
+ * satisfies it. Add it in your app: `pnpm add redis`.
+ *
+ * `set` must support the `NX` (set-if-absent) and `PX` (ms TTL) options and
+ * return `null` when `NX` prevented the write. `eval` is used for atomic
+ * owner-aware completion/release transitions.
+ */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        PX?: number;
+        NX?: boolean;
+    }): Promise<string | null>;
+    del(key: string): Promise<number>;
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+}
+/** Options for {@link RedisIdempotencyStore}. */
+export interface RedisIdempotencyStoreOptions {
+    /** Prefix applied to every Redis key. Default `'idempotency:'`. */
+    keyPrefix?: string;
+}
+/**
+ * {@link IdempotencyStore} backed by **Redis** (node-redis) — a drop-in
+ * replacement for the memory store that shares state across instances.
+ *
+ * Atomicity comes from Redis itself: {@link setIfAbsent} issues
+ * `SET key value PX <ttl> NX`, which sets the key only if it does not already
+ * exist and returns `null` otherwise. Owner-aware completion and release use
+ * Lua scripts so a stale execution cannot overwrite/delete a newer claim.
+ * TTL is enforced by Redis, so expired keys never linger.
+ *
+ * A stored value that is not valid JSON fails closed: {@link get} throws, and
+ * the owner-aware writes cannot prove ownership of it, so they leave it
+ * untouched and return `false`.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'redis';
+ * const client = createClient({ url: process.env.REDIS_URL });
+ * await client.connect();
+ * const store = new RedisIdempotencyStore(client);
+ * ```
+ */
+export declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly client;
+    private readonly prefix;
+    constructor(client: RedisClientLike, options?: RedisIdempotencyStoreOptions);
+    get(key: string): Promise<IdempotencyRecord | undefined>;
+    setIfAbsent(key: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
+    completeIfOwned(key: string, claimId: string, record: IdempotencyRecord, ttlMs: number): Promise<boolean>;
+    deleteIfOwned(key: string, claimId: string): Promise<boolean>;
+    set(key: string, record: IdempotencyRecord, ttlMs: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=redis.store.d.ts.map

package/dist/stores/redis.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.store.d.ts","sourceRoot":"","sources":["../../src/stores/redis.store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAqBrF;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CACF,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAC/C,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAI1D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,YACmB,MAAM,EAAE,eAAe,EACxC,OAAO,GAAE,4BAAiC,EAG3C;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAG7D;IAEK,WAAW,CACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;IAEK,eAAe,CACnB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAMlB;IAEK,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMlE;IAEK,GAAG,CACP,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAIf;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;CACF"}

package/dist/stores/redis.store.js

@@ -0,0 +1,79 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+const COMPLETE_IF_OWNED_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local ok, current = pcall(cjson.decode, raw)
+if not ok then return 0 end
+if current.status ~= 'in_progress' or current.claimId ~= ARGV[1] then return 0 end
+redis.call('SET', KEYS[1], ARGV[2], 'PX', ARGV[3])
+return 1
+`;
+const DELETE_IF_OWNED_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local ok, current = pcall(cjson.decode, raw)
+if not ok then return 0 end
+if current.claimId ~= ARGV[1] then return 0 end
+return redis.call('DEL', KEYS[1])
+`;
+/**
+ * {@link IdempotencyStore} backed by **Redis** (node-redis) — a drop-in
+ * replacement for the memory store that shares state across instances.
+ *
+ * Atomicity comes from Redis itself: {@link setIfAbsent} issues
+ * `SET key value PX <ttl> NX`, which sets the key only if it does not already
+ * exist and returns `null` otherwise. Owner-aware completion and release use
+ * Lua scripts so a stale execution cannot overwrite/delete a newer claim.
+ * TTL is enforced by Redis, so expired keys never linger.
+ *
+ * A stored value that is not valid JSON fails closed: {@link get} throws, and
+ * the owner-aware writes cannot prove ownership of it, so they leave it
+ * untouched and return `false`.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'redis';
+ * const client = createClient({ url: process.env.REDIS_URL });
+ * await client.connect();
+ * const store = new RedisIdempotencyStore(client);
+ * ```
+ */
+export class RedisIdempotencyStore {
+    client;
+    prefix;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.prefix = options.keyPrefix ?? 'idempotency:';
+    }
+    async get(key) {
+        const raw = await this.client.get(this.prefix + key);
+        return raw ? JSON.parse(raw) : undefined;
+    }
+    async setIfAbsent(key, record, ttlMs) {
+        const result = await this.client.set(this.prefix + key, JSON.stringify(record), { PX: ttlMs, NX: true });
+        return result !== null;
+    }
+    async completeIfOwned(key, claimId, record, ttlMs) {
+        const result = await this.client.eval(COMPLETE_IF_OWNED_SCRIPT, {
+            keys: [this.prefix + key],
+            arguments: [claimId, JSON.stringify(record), String(ttlMs)],
+        });
+        return Number(result) === 1;
+    }
+    async deleteIfOwned(key, claimId) {
+        const result = await this.client.eval(DELETE_IF_OWNED_SCRIPT, {
+            keys: [this.prefix + key],
+            arguments: [claimId],
+        });
+        return Number(result) === 1;
+    }
+    async set(key, record, ttlMs) {
+        await this.client.set(this.prefix + key, JSON.stringify(record), {
+            PX: ttlMs,
+        });
+    }
+    async delete(key) {
+        await this.client.del(this.prefix + key);
+    }
+}
+//# sourceMappingURL=redis.store.js.map

package/dist/stores/redis.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.store.js","sourceRoot":"","sources":["../../src/stores/redis.store.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAKtE,MAAM,wBAAwB,GAAG;;;;;;;;CAQhC,CAAC;AAEF,MAAM,sBAAsB,GAAG;;;;;;;CAO9B,CAAC;AA+BF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,qBAAqB;IAIb,MAAM;IAHR,MAAM,CAAS;IAEhC,YACmB,MAAuB,EACxC,OAAO,GAAiC,EAAE;sBADzB,MAAM;QAGvB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,SAAS,IAAI,cAAc,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QACrD,OAAO,GAAG,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,WAAW,CACf,GAAW,EACX,MAAyB,EACzB,KAAa;QAEb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAClC,IAAI,CAAC,MAAM,GAAG,GAAG,EACjB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EACtB,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,CACxB,CAAC;QACF,OAAO,MAAM,KAAK,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,GAAW,EACX,OAAe,EACf,MAAyB,EACzB,KAAa;QAEb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE;YAC9D,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;YACzB,SAAS,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;SAC5D,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,OAAe;QAC9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE;YAC5D,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;YACzB,SAAS,EAAE,CAAC,OAAO,CAAC;SACrB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,GAAG,CACP,GAAW,EACX,MAAyB,EACzB,KAAa;QAEb,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE;YAC/D,EAAE,EAAE,KAAK;SACV,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@cqrs-ddd/pipeline-idempotency",
+  "version": "0.5.0",
+  "description": "Idempotency for @cqrs-ddd/pipeline: deduplicates commands by an operation key and replays completed responses within the caller's scope",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "pipeline",
+    "cqrs",
+    "idempotency",
+    "idempotent",
+    "deduplication",
+    "retry-safe",
+    "behavior"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/ddd-cqrs.git",
+    "directory": "packages/pipeline-idempotency"
+  },
+  "homepage": "https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-idempotency/",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/ddd-cqrs/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@cqrs-ddd/pipeline": "^0.5.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^5.0.3",
+    "vitest": "^5.0.3",
+    "@cqrs-ddd/pipeline": "0.5.0"
+  },
+  "dependencies": {
+    "@cqrs-ddd/untyped": "^0.5.0",
+    "@cqrs-ddd/safe-stringify": "^0.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}