@hardkas/toolkit 0.11.1-alpha

package/src/snapshot/backends/FsSnapshotBackend.ts

@@ -0,0 +1,100 @@
+import { SnapshotBackend, SnapshotManifest, SnapshotState } from "../types.js";
+import fs from "fs-extra";
+import path from "path";
+import crypto from "crypto";
+import { snapshotReplacer, snapshotReviver } from "../serialization.js";
+
+export class FsSnapshotBackend implements SnapshotBackend {
+    private baseDir: string;
+
+    constructor(baseDir: string = ".hardkas-snapshots") {
+        this.baseDir = baseDir;
+    }
+
+    async save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest> {
+        const snapshotDir = path.join(this.baseDir, id);
+        await fs.ensureDir(snapshotDir);
+
+        const stateHashes: Record<string, string> = {};
+        const participants = Object.keys(state);
+
+        // Write each participant's state to a separate file
+        for (const [pId, pState] of Object.entries(state)) {
+            const data = JSON.stringify(pState, snapshotReplacer, 2);
+            stateHashes[pId] = crypto.createHash("sha256").update(data).digest("hex");
+            await fs.writeFile(path.join(snapshotDir, `${pId}.json`), data);
+        }
+
+        const manifest: SnapshotManifest = {
+            schema: "hardkas.snapshot.v1",
+            snapshotId: id,
+            name,
+            createdAt: Date.now(),
+            backend: "filesystem",
+            path: snapshotDir,
+            participants,
+            stateHashes,
+            claims: {
+                containsFullStateInline: false,
+                restorableLocalState: true,
+                networkStateCaptured: false
+            }
+        };
+
+        // Write manifest
+        await fs.writeFile(path.join(snapshotDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+
+        return manifest;
+    }
+
+    async load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }> {
+        const snapshotDir = path.join(this.baseDir, id);
+        if (!await fs.pathExists(snapshotDir)) {
+            throw new Error(`Snapshot ${id} not found in filesystem backend at ${snapshotDir}`);
+        }
+
+        const manifestData = await fs.readFile(path.join(snapshotDir, "manifest.json"), "utf8");
+        const manifest: SnapshotManifest = JSON.parse(manifestData);
+
+        const state: Record<string, SnapshotState> = {};
+        for (const pId of manifest.participants) {
+            const stateData = await fs.readFile(path.join(snapshotDir, `${pId}.json`), "utf8");
+            state[pId] = JSON.parse(stateData, snapshotReviver);
+        }
+
+        return { manifest, state };
+    }
+
+    async list(): Promise<SnapshotManifest[]> {
+        if (!await fs.pathExists(this.baseDir)) {
+            return [];
+        }
+
+        const entries = await fs.readdir(this.baseDir, { withFileTypes: true });
+        const manifests: SnapshotManifest[] = [];
+
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const manifestPath = path.join(this.baseDir, entry.name, "manifest.json");
+                if (await fs.pathExists(manifestPath)) {
+                    const data = await fs.readFile(manifestPath, "utf8");
+                    manifests.push(JSON.parse(data));
+                }
+            }
+        }
+
+        return manifests;
+    }
+
+    async delete(id: string): Promise<void> {
+        const snapshotDir = path.join(this.baseDir, id);
+        if (await fs.pathExists(snapshotDir)) {
+            await fs.remove(snapshotDir);
+        }
+    }
+
+    async branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest> {
+        const { state } = await this.load(baseId);
+        return this.save(newId, newName, state);
+    }
+}

package/src/snapshot/backends/MemorySnapshotBackend.ts

@@ -0,0 +1,65 @@
+import { SnapshotBackend, SnapshotManifest, SnapshotState } from "../types.js";
+import crypto from "crypto";
+import { snapshotReplacer, snapshotReviver } from "../serialization.js";
+
+export class MemorySnapshotBackend implements SnapshotBackend {
+    private snapshots = new Map<string, { manifest: SnapshotManifest; state: Record<string, SnapshotState> }>();
+
+    async save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest> {
+        const stateHashes: Record<string, string> = {};
+        const participants = Object.keys(state);
+
+        for (const [pId, pState] of Object.entries(state)) {
+            stateHashes[pId] = crypto.createHash("sha256").update(JSON.stringify(pState, snapshotReplacer)).digest("hex");
+        }
+
+        const manifest: SnapshotManifest = {
+            schema: "hardkas.snapshot.v1",
+            snapshotId: id,
+            name,
+            createdAt: Date.now(),
+            backend: "memory",
+            participants,
+            stateHashes,
+            claims: {
+                containsFullStateInline: true,
+                restorableLocalState: true,
+                networkStateCaptured: false
+            }
+        };
+
+        // Deep copy state to ensure isolation
+        const deepCopiedState = JSON.parse(JSON.stringify(state, snapshotReplacer), snapshotReviver);
+        this.snapshots.set(id, { manifest, state: deepCopiedState });
+
+        return manifest;
+    }
+
+    async load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }> {
+        const entry = this.snapshots.get(id);
+        if (!entry) {
+            throw new Error(`Snapshot ${id} not found in memory backend`);
+        }
+        // Return a deep copy to prevent mutation of the snapshot itself
+        return {
+            manifest: JSON.parse(JSON.stringify(entry.manifest)),
+            state: JSON.parse(JSON.stringify(entry.state, snapshotReplacer), snapshotReviver)
+        };
+    }
+
+    async list(): Promise<SnapshotManifest[]> {
+        return Array.from(this.snapshots.values()).map(s => s.manifest);
+    }
+
+    async delete(id: string): Promise<void> {
+        this.snapshots.delete(id);
+    }
+
+    async branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest> {
+        const entry = this.snapshots.get(baseId);
+        if (!entry) throw new Error(`Base snapshot ${baseId} not found`);
+
+        const newState = JSON.parse(JSON.stringify(entry.state, snapshotReplacer), snapshotReviver);
+        return this.save(newId, newName, newState);
+    }
+}

package/src/snapshot/index.ts

@@ -0,0 +1,102 @@
+import { SnapshotBackend, SnapshotManifest, SnapshotParticipant, SnapshotState } from "./types.js";
+import { MemorySnapshotBackend } from "./backends/MemorySnapshotBackend.js";
+import { FsSnapshotBackend } from "./backends/FsSnapshotBackend.js";
+import crypto from "crypto";
+
+export interface SnapshotToolkitOptions {
+    backend?: "memory" | "filesystem";
+    dir?: string;
+}
+
+export class SnapshotToolkit {
+    private backend: SnapshotBackend;
+    private participants = new Map<string, SnapshotParticipant>();
+
+    private constructor(options: SnapshotToolkitOptions) {
+        if (options.backend === "filesystem") {
+            this.backend = new FsSnapshotBackend(options.dir);
+        } else {
+            this.backend = new MemorySnapshotBackend();
+        }
+    }
+
+    public static open(options: SnapshotToolkitOptions = { backend: "memory" }): SnapshotToolkit {
+        return new SnapshotToolkit(options);
+    }
+
+    public register(id: string, participant: SnapshotParticipant): void {
+        this.participants.set(id, participant);
+    }
+
+    public async create(name: string): Promise<SnapshotManifest> {
+        const id = crypto.randomUUID();
+        const state: Record<string, SnapshotState> = {};
+
+        // Snapshot all participants
+        for (const [pId, participant] of this.participants.entries()) {
+            state[pId] = await participant.snapshot();
+        }
+
+        return this.backend.save(id, name, state);
+    }
+
+    public async restore(id: string): Promise<void> {
+        const { state } = await this.backend.load(id);
+
+        // 1. load state & restore (but don't reload yet in case something fails)
+        for (const [pId, pState] of Object.entries(state)) {
+            const participant = this.participants.get(pId);
+            if (!participant) {
+                throw new Error(`Cannot restore state for participant '${pId}' because it is not registered`);
+            }
+            try {
+                await participant.restore(pState);
+            } catch (err: any) {
+                throw new Error(`Failed to restore participant '${pId}': ${err.message}`);
+            }
+        }
+
+        // 2. reload all
+        for (const [pId, _] of Object.entries(state)) {
+            const participant = this.participants.get(pId)!;
+            try {
+                await participant.reload();
+            } catch (err: any) {
+                throw new Error(`Failed to reload participant '${pId}' after restoration: ${err.message}`);
+            }
+        }
+    }
+
+    public async branch(baseId: string, newName: string): Promise<SnapshotManifest> {
+        const newId = crypto.randomUUID();
+        return this.backend.branch(baseId, newId, newName);
+    }
+
+    public async diff(idA: string, idB: string): Promise<Record<string, any>> {
+        const [a, b] = await Promise.all([this.backend.load(idA), this.backend.load(idB)]);
+        
+        const differences: Record<string, any> = {};
+        const allParticipants = new Set([...a.manifest.participants, ...b.manifest.participants]);
+
+        for (const pId of allParticipants) {
+            const hashA = a.manifest.stateHashes[pId];
+            const hashB = b.manifest.stateHashes[pId];
+            if (hashA !== hashB) {
+                differences[pId] = {
+                    a: a.state[pId] || null,
+                    b: b.state[pId] || null
+                };
+            }
+        }
+        return differences;
+    }
+
+    public async compare(idA: string, idB: string): Promise<boolean> {
+        const diff = await this.diff(idA, idB);
+        return Object.keys(diff).length === 0;
+    }
+
+    public async list(): Promise<SnapshotManifest[]> {
+        return this.backend.list();
+    }
+}

package/src/snapshot/serialization.ts

@@ -0,0 +1,35 @@
+import { SnapshotState } from "./types.js";
+
+/**
+ * Custom JSON Replacer to safely serialize BigInt values.
+ */
+export function snapshotReplacer(key: string, value: any): any {
+    if (typeof value === "bigint") {
+        return { $bigint: value.toString() };
+    }
+    return value;
+}
+
+/**
+ * Custom JSON Reviver to safely deserialize BigInt values.
+ */
+export function snapshotReviver(key: string, value: any): any {
+    if (value !== null && typeof value === "object" && typeof value.$bigint === "string") {
+        return BigInt(value.$bigint);
+    }
+    return value;
+}
+
+/**
+ * Serializes a SnapshotState map to a string safely supporting BigInt.
+ */
+export function serializeState(state: Record<string, SnapshotState>): string {
+    return JSON.stringify(state, snapshotReplacer, 2);
+}
+
+/**
+ * Deserializes a SnapshotState map from a string safely supporting BigInt.
+ */
+export function deserializeState(data: string): Record<string, SnapshotState> {
+    return JSON.parse(data, snapshotReviver);
+}

package/src/snapshot/types.ts

@@ -0,0 +1,45 @@
+export interface SnapshotState {
+    [key: string]: any;
+}
+
+export interface SnapshotParticipant {
+    /** 
+     * Extracts the current internal state of the toolkit/store 
+     */
+    snapshot(): Promise<SnapshotState>;
+
+    /** 
+     * Restores the internal state from the provided snapshot state 
+     */
+    restore(state: SnapshotState): Promise<void>;
+
+    /** 
+     * Reloads any caches, queues, or in-memory representations 
+     * based on the newly restored state 
+     */
+    reload(): Promise<void>;
+}
+
+export interface SnapshotManifest {
+    schema: "hardkas.snapshot.v1";
+    snapshotId: string;
+    name: string;
+    createdAt: number;
+    backend: "memory" | "filesystem";
+    path?: string;
+    participants: string[];
+    stateHashes: Record<string, string>;
+    claims: {
+        containsFullStateInline: boolean;
+        restorableLocalState: boolean;
+        networkStateCaptured: boolean;
+    };
+}
+
+export interface SnapshotBackend {
+    save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest>;
+    load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }>;
+    list(): Promise<SnapshotManifest[]>;
+    delete(id: string): Promise<void>;
+    branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest>;
+}

package/src/stores/invoice-store.ts

@@ -0,0 +1,53 @@
+import { DomainStoreJson } from '@hardkas/query-store';
+
+export interface InvoiceRecord {
+    id: string;
+    merchantId: string;
+    amount: bigint;
+    currency: string;
+    status: 'pending' | 'paid' | 'cancelled';
+    uri: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export class InvoiceStoreJson {
+    private store: DomainStoreJson<InvoiceRecord>;
+
+    constructor(options: { filePath: string }) {
+        this.store = new DomainStoreJson<InvoiceRecord>(options);
+    }
+
+    public save(invoice: InvoiceRecord): void {
+        invoice.updatedAt = new Date().toISOString();
+        this.store.save(invoice.id, invoice);
+    }
+
+    public get(id: string): InvoiceRecord | undefined {
+        return this.store.get(id);
+    }
+
+    public list(): InvoiceRecord[] {
+        return this.store.list();
+    }
+
+    public listByMerchant(merchantId: string): InvoiceRecord[] {
+        return this.store.list().filter(i => i.merchantId === merchantId);
+    }
+
+    public listPaid(): InvoiceRecord[] {
+        return this.store.list().filter(i => i.status === 'paid');
+    }
+
+    public stats(merchantId?: string) {
+        let invoices = this.store.list();
+        if (merchantId) {
+            invoices = invoices.filter(i => i.merchantId === merchantId);
+        }
+        
+        return {
+            totalInvoices: invoices.length,
+            paidInvoices: invoices.filter(i => i.status === 'paid').length
+        };
+    }
+}

package/src/stores/utxo-control-store.ts

@@ -0,0 +1,78 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface UtxoControlState {
+  frozen: Record<string, { reason?: string | undefined; timestamp: number }>;
+  labels: Record<string, string>;
+  notes: Record<string, string>;
+}
+
+export class UtxoControlStore {
+  private filePath: string;
+  private state: UtxoControlState;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.state = this.load();
+  }
+
+  private load(): UtxoControlState {
+    try {
+      if (fs.existsSync(this.filePath)) {
+        const data = fs.readFileSync(this.filePath, 'utf-8');
+        return JSON.parse(data) as UtxoControlState;
+      }
+    } catch (e) {
+      // Ignore read errors, initialize default
+    }
+    return {
+      frozen: {},
+      labels: {},
+      notes: {}
+    };
+  }
+
+  private save(): void {
+    try {
+      const dir = path.dirname(this.filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.filePath, JSON.stringify(this.state, null, 2), 'utf-8');
+    } catch (e) {
+      console.warn(`Failed to save UTXO control state to ${this.filePath}`, e);
+    }
+  }
+
+  public getState(): UtxoControlState {
+    return JSON.parse(JSON.stringify(this.state)); // Deep copy
+  }
+
+  public freeze(utxoId: string, reason?: string): void {
+    this.state.frozen[utxoId] = { reason, timestamp: Date.now() };
+    this.save();
+  }
+
+  public unfreeze(utxoId: string): void {
+    delete this.state.frozen[utxoId];
+    this.save();
+  }
+
+  public setLabel(utxoId: string, label: string): void {
+    this.state.labels[utxoId] = label;
+    this.save();
+  }
+
+  public getLabel(utxoId: string): string | undefined {
+    return this.state.labels[utxoId];
+  }
+
+  public setNote(utxoId: string, note: string): void {
+    this.state.notes[utxoId] = note;
+    this.save();
+  }
+
+  public getNote(utxoId: string): string | undefined {
+    return this.state.notes[utxoId];
+  }
+}