@jolly-pixel/asset-server 1.0.0

package/dist/sync/ProjectionState.d.ts

@@ -0,0 +1,33 @@
+import { type AssetSource } from "@jolly-pixel/asset-source";
+import { type Logger } from "../logger.ts";
+export interface ProjectionFailure {
+    readonly eventId: number;
+    readonly attempts: number;
+    readonly reason: string;
+}
+export interface ProjectionStateParse {
+    readonly data: ProjectionStateData | null;
+    readonly dropped: number;
+}
+export interface ProjectionStateData {
+    readonly version: 1;
+    readonly checkpoints: Record<string, number>;
+    readonly failures: Record<string, ProjectionFailure>;
+}
+/**
+ * Persists each asset's last successfully projected event id.
+ */
+export declare class ProjectionState {
+    #private;
+    constructor(source: AssetSource, data?: ProjectionStateData | null);
+    checkpoint(assetId: string): number;
+    failure(assetId: string): ProjectionFailure | undefined;
+    advance(assetId: string, eventId: number): void;
+    recordFailure(assetId: string, eventId: number, reason: string): void;
+    forget(assetId: string): void;
+    toJSON(): ProjectionStateData;
+    save(): Promise<void>;
+    static load(source: AssetSource, logger?: Logger): Promise<ProjectionState>;
+    static parse(input: unknown): ProjectionStateParse;
+}
+//# sourceMappingURL=ProjectionState.d.ts.map

package/dist/sync/ProjectionState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectionState.d.ts","sourceRoot":"","sources":["../../src/sync/ProjectionState.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AA+BtB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAOD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CACtD;AAED;;GAEG;AACH,qBAAa,eAAe;;gBAMxB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,mBAAmB,GAAG,IAAW;IAqBzC,UAAU,CACR,OAAO,EAAE,MAAM,GACd,MAAM;IAIT,OAAO,CACL,OAAO,EAAE,MAAM,GACd,iBAAiB,GAAG,SAAS;IAIhC,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,IAAI;IAKP,aAAa,CACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,IAAI;IASP,MAAM,CACJ,OAAO,EAAE,MAAM,GACd,IAAI;IAKP,MAAM,IAAI,mBAAmB;IAgB7B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;WAQR,IAAI,CACf,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,MAAuB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAmB3B,MAAM,CAAC,KAAK,CACV,KAAK,EAAE,OAAO,GACb,oBAAoB;CA0BxB"}

package/dist/sync/ProjectionState.js

@@ -0,0 +1,129 @@
+// Import Third-party Dependencies
+import { defineSchema, Validator } from "ata-validator";
+import { readJsonFile, writeJsonFile } from "@jolly-pixel/asset-source";
+// Import Internal Dependencies
+import { silentLogger } from "../logger.js";
+import { PROJECTION_STATE_PATH } from "../constants.js";
+// CONSTANTS
+const kStateVersion = 1;
+const kValidatorOptions = { useDefaults: false };
+const kRecordValidator = new Validator(defineSchema({ type: "object" }), kValidatorOptions);
+const kCheckpointValidator = new Validator(defineSchema({ type: "integer" }), kValidatorOptions);
+const kFailureValidator = new Validator(defineSchema({
+    type: "object",
+    properties: {
+        eventId: { type: "integer" },
+        attempts: { type: "integer" },
+        reason: { type: "string" }
+    },
+    required: [
+        "eventId",
+        "attempts",
+        "reason"
+    ]
+}), kValidatorOptions);
+/**
+ * Persists each asset's last successfully projected event id.
+ */
+export class ProjectionState {
+    #checkpoints = new Map();
+    #failures = new Map();
+    #source;
+    constructor(source, data = null) {
+        this.#source = source;
+        if (data === null) {
+            return;
+        }
+        for (const [assetId, eventId] of Object.entries(data.checkpoints)) {
+            this.#checkpoints.set(assetId, eventId);
+        }
+        for (const [assetId, failure] of Object.entries(data.failures)) {
+            this.#failures.set(assetId, failure);
+        }
+    }
+    checkpoint(assetId) {
+        return this.#checkpoints.get(assetId) ?? 0;
+    }
+    failure(assetId) {
+        return this.#failures.get(assetId);
+    }
+    advance(assetId, eventId) {
+        this.#checkpoints.set(assetId, eventId);
+        this.#failures.delete(assetId);
+    }
+    recordFailure(assetId, eventId, reason) {
+        const previous = this.#failures.get(assetId);
+        this.#failures.set(assetId, {
+            eventId,
+            attempts: previous?.eventId === eventId ? previous.attempts + 1 : 1,
+            reason
+        });
+    }
+    forget(assetId) {
+        this.#checkpoints.delete(assetId);
+        this.#failures.delete(assetId);
+    }
+    toJSON() {
+        return {
+            version: kStateVersion,
+            checkpoints: Object.fromEntries([...this.#checkpoints.entries()].sort(([a], [b]) => a.localeCompare(b))),
+            failures: Object.fromEntries([...this.#failures.entries()].sort(([a], [b]) => a.localeCompare(b)))
+        };
+    }
+    save() {
+        return writeJsonFile(this.#source, PROJECTION_STATE_PATH, this.toJSON());
+    }
+    static async load(source, logger = silentLogger()) {
+        const { data, dropped } = ProjectionState.parse(await readJsonFile(source, PROJECTION_STATE_PATH));
+        if (dropped > 0) {
+            logger
+                .withMetadata({
+                path: PROJECTION_STATE_PATH,
+                dropped
+            })
+                .warn("projection state entries dropped");
+        }
+        return new ProjectionState(source, data);
+    }
+    static parse(input) {
+        if (!kRecordValidator.isValidObject(input)) {
+            return {
+                data: null,
+                dropped: 0
+            };
+        }
+        const checkpoints = pickEntries(input.checkpoints, kCheckpointValidator);
+        const failures = pickEntries(input.failures, kFailureValidator);
+        return {
+            data: {
+                version: kStateVersion,
+                checkpoints: checkpoints.entries,
+                failures: failures.entries
+            },
+            dropped: checkpoints.dropped + failures.dropped
+        };
+    }
+}
+function pickEntries(input, validator) {
+    if (!kRecordValidator.isValidObject(input)) {
+        return {
+            entries: {},
+            dropped: 0
+        };
+    }
+    const entries = {};
+    let dropped = 0;
+    for (const [key, value] of Object.entries(input)) {
+        const result = validator.validate(value);
+        if (result.valid) {
+            entries[key] = result.data;
+        }
+        else {
+            dropped += 1;
+        }
+    }
+    return {
+        entries,
+        dropped
+    };
+}

package/dist/sync/Reconciler.d.ts

@@ -0,0 +1,36 @@
+import type * as EventStore from "@jolly-pixel/event-store";
+import { type Result } from "@openally/result";
+import type { AssetSource } from "@jolly-pixel/asset-source";
+import type { AssetKindRegistry } from "../kinds/AssetKindRegistry.ts";
+import { type Logger } from "../logger.ts";
+import type { AssetProjector } from "./AssetProjector.ts";
+import type { AssetWriter } from "./AssetWriter.ts";
+export interface ReconcileReport {
+    readonly created: number;
+    readonly updated: number;
+    readonly renamed: number;
+    readonly deleted: number;
+    /**
+     * Entries skipped after an append or read failure.
+     */
+    readonly failed: number;
+}
+export interface ReconcilerOptions {
+    source: AssetSource;
+    projector: AssetProjector;
+    writer: AssetWriter;
+    kinds: AssetKindRegistry;
+    actor?: EventStore.Actor;
+    logger?: Logger;
+}
+/**
+ * Reconciles physical files against the last projected event state.
+ *
+ * Hash equality suppresses echoed writes and makes notifications idempotent.
+ */
+export declare class Reconciler {
+    #private;
+    constructor(options: ReconcilerOptions);
+    reconcile(): Promise<Result<ReconcileReport, Error>>;
+}
+//# sourceMappingURL=Reconciler.d.ts.map

package/dist/sync/Reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reconciler.d.ts","sourceRoot":"","sources":["../../src/sync/Reconciler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,UAAU,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAQvE,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AASpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA+BD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,UAAU;;gBASnB,OAAO,EAAE,iBAAiB;IAUtB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;CA4K3D"}

package/dist/sync/Reconciler.js

@@ -0,0 +1,182 @@
+// Import Node.js Dependencies
+import { randomUUID } from "node:crypto";
+import { Err, Ok } from "@openally/result";
+import { contentHash } from "../utils/contentHash.js";
+import { matchRenames } from "./matchRenames.js";
+import { silentLogger } from "../logger.js";
+// CONSTANTS
+const kWatcherActor = {
+    type: "system",
+    source: "fs-watcher"
+};
+const kReadConcurrency = 16;
+/**
+ * Reconciles physical files against the last projected event state.
+ *
+ * Hash equality suppresses echoed writes and makes notifications idempotent.
+ */
+export class Reconciler {
+    #source;
+    #projector;
+    #writer;
+    #kinds;
+    #actor;
+    #logger;
+    constructor(options) {
+        this.#source = options.source;
+        this.#projector = options.projector;
+        this.#writer = options.writer;
+        this.#kinds = options.kinds;
+        this.#actor = options.actor ?? kWatcherActor;
+        this.#logger = options.logger ?? silentLogger();
+    }
+    async reconcile() {
+        let scan;
+        try {
+            scan = await this.#observe();
+        }
+        catch (error) {
+            return Err(asError(error));
+        }
+        const projected = [];
+        for (const { assetId, projection } of this.#projector.projections()) {
+            if (scan.unreadable.has(projection.path)) {
+                continue;
+            }
+            projected.push({
+                id: assetId,
+                path: projection.path,
+                kind: projection.kind,
+                hash: projection.hash
+            });
+        }
+        const diff = matchRenames(projected, scan.entries);
+        const report = {
+            created: 0,
+            updated: 0,
+            renamed: 0,
+            deleted: 0,
+            failed: scan.unreadable.size
+        };
+        for (const operation of this.#plan(diff)) {
+            await this.#apply(operation, report);
+        }
+        if (this.#total(report) > 0) {
+            this.#logger
+                .withMetadata({ ...report })
+                .info("reconciled external changes");
+        }
+        return Ok(report);
+    }
+    *#plan(diff) {
+        for (const entry of diff.deleted) {
+            yield {
+                outcome: "deleted",
+                path: entry.path,
+                run: () => this.#writer.remove({
+                    assetId: entry.id,
+                    actor: this.#actor,
+                    alreadyProjected: true
+                })
+            };
+        }
+        for (const entry of diff.renamed) {
+            yield {
+                outcome: "renamed",
+                path: entry.to,
+                run: () => this.#writer.rename({
+                    assetId: entry.id,
+                    to: entry.to,
+                    actor: this.#actor,
+                    alreadyProjected: true
+                })
+            };
+        }
+        for (const entry of diff.updated) {
+            yield {
+                outcome: "updated",
+                path: entry.path,
+                run: async () => this.#writer.update({
+                    assetId: entry.id,
+                    data: await this.#source.read(entry.path),
+                    actor: this.#actor,
+                    alreadyProjected: true
+                })
+            };
+        }
+        for (const entry of diff.created) {
+            yield {
+                outcome: "created",
+                path: entry.path,
+                run: async () => this.#writer.create({
+                    path: entry.path,
+                    data: await this.#source.read(entry.path),
+                    kind: this.#kinds.resolve(entry.path).kind,
+                    assetId: this.#writer.identity.byPath(entry.path)?.id ?? randomUUID(),
+                    actor: this.#actor,
+                    alreadyProjected: true
+                })
+            };
+        }
+    }
+    async #apply(operation, report) {
+        const result = await operation.run()
+            .catch((error) => Err(asError(error)));
+        if (result.ok) {
+            report[operation.outcome] += 1;
+            return;
+        }
+        report.failed += 1;
+        this.#logger
+            .withMetadata({
+            path: operation.path,
+            outcome: operation.outcome,
+            reason: result.val.message
+        })
+            .error("asset reconciliation failed");
+    }
+    #total(report) {
+        return report.created +
+            report.updated +
+            report.renamed +
+            report.deleted +
+            report.failed;
+    }
+    async #observe() {
+        const paths = await this.#source.list();
+        const entries = [];
+        const unreadable = new Set();
+        for (let index = 0; index < paths.length; index += kReadConcurrency) {
+            const batch = paths.slice(index, index + kReadConcurrency);
+            const results = await Promise.all(batch.map(async (path) => {
+                try {
+                    return {
+                        path,
+                        entry: {
+                            path,
+                            hash: contentHash(await this.#source.read(path))
+                        }
+                    };
+                }
+                catch (error) {
+                    this.#logger
+                        .withMetadata({ path, reason: asError(error).message })
+                        .warn("asset not readable, left untouched");
+                    return { path, entry: null };
+                }
+            }));
+            for (const { path, entry } of results) {
+                if (entry === null) {
+                    unreadable.add(path);
+                }
+                else {
+                    entries.push(entry);
+                }
+            }
+        }
+        return { entries, unreadable };
+    }
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/sync/ReconciliationWatcher.d.ts

@@ -0,0 +1,28 @@
+import type { AssetSource } from "@jolly-pixel/asset-source";
+import { type Logger } from "../logger.ts";
+import type { Reconciler } from "./Reconciler.ts";
+export interface ReconciliationWatcherOptions {
+    source: AssetSource;
+    reconciler: Reconciler;
+    /**
+     * Quiet period, in milliseconds, before a batch of notifications turns
+     * into one reconciliation pass.
+     * @default 200
+     */
+    debounce?: number;
+    logger?: Logger;
+}
+/**
+ * Coalesces filesystem notifications into idempotent reconciliation passes.
+ */
+export declare class ReconciliationWatcher {
+    #private;
+    constructor(options: ReconciliationWatcherOptions);
+    get watching(): boolean;
+    start(): void;
+    notify(path: string): void;
+    run(): Promise<void>;
+    settle(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=ReconciliationWatcher.d.ts.map

package/dist/sync/ReconciliationWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReconciliationWatcher.d.ts","sourceRoot":"","sources":["../../src/sync/ReconciliationWatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAG7D,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKlD,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,qBAAqB;;gBAY9B,OAAO,EAAE,4BAA4B;IAQvC,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,IAAI,IAAI;IAWb,MAAM,CACJ,IAAI,EAAE,MAAM,GACX,IAAI;IAeP,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBd,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA6B7B"}

package/dist/sync/ReconciliationWatcher.js

@@ -0,0 +1,86 @@
+// Import Internal Dependencies
+import { silentLogger } from "../logger.js";
+// CONSTANTS
+const kDefaultDebounce = 200;
+/**
+ * Coalesces filesystem notifications into idempotent reconciliation passes.
+ */
+export class ReconciliationWatcher {
+    #source;
+    #reconciler;
+    #debounce;
+    #logger;
+    #unwatch = null;
+    #handle = null;
+    #running = null;
+    #again = false;
+    constructor(options) {
+        this.#source = options.source;
+        this.#reconciler = options.reconciler;
+        this.#debounce = options.debounce ?? kDefaultDebounce;
+        this.#logger = options.logger ?? silentLogger();
+    }
+    get watching() {
+        return this.#unwatch !== null;
+    }
+    start() {
+        if (this.#unwatch !== null ||
+            this.#source.watch === undefined) {
+            return;
+        }
+        this.#unwatch = this.#source.watch((path) => this.notify(path));
+    }
+    notify(path) {
+        this.#logger
+            .withMetadata({ path })
+            .debug("filesystem change observed");
+        if (this.#handle !== null) {
+            clearTimeout(this.#handle);
+        }
+        this.#handle = setTimeout(() => void this.run(), this.#debounce);
+        this.#handle.unref();
+    }
+    run() {
+        if (this.#handle !== null) {
+            clearTimeout(this.#handle);
+            this.#handle = null;
+        }
+        if (this.#running !== null) {
+            this.#again = true;
+            return this.#running;
+        }
+        const pass = this.#run();
+        this.#running = pass;
+        return pass;
+    }
+    async settle() {
+        await this.#running;
+    }
+    async close() {
+        if (this.#unwatch !== null) {
+            this.#unwatch();
+            this.#unwatch = null;
+        }
+        if (this.#handle !== null) {
+            clearTimeout(this.#handle);
+            this.#handle = null;
+        }
+        await this.#running;
+    }
+    async #run() {
+        try {
+            do {
+                this.#again = false;
+                const result = await this.#reconciler.reconcile();
+                if (!result.ok) {
+                    this.#logger
+                        .withMetadata({ reason: result.val.message })
+                        .error("reconciliation failed");
+                }
+            } while (this.#again);
+        }
+        finally {
+            this.#running = null;
+        }
+    }
+}

package/dist/sync/SnapshotScheduler.d.ts

@@ -0,0 +1,29 @@
+import type * as EventStore from "@jolly-pixel/event-store";
+import { type Logger } from "../logger.ts";
+import { type AssetEventDataMap } from "../events/AssetEvents.ts";
+import type { SnapshotPolicy } from "../kinds/AssetKindHandler.ts";
+import type { AssetStateStore } from "./AssetStateStore.ts";
+import type { AssetProjector } from "./AssetProjector.ts";
+export interface SnapshotSchedulerOptions {
+    eventStore: EventStore.TypedEventStore<AssetEventDataMap>;
+    states: AssetStateStore;
+    projector: AssetProjector;
+    snapshot?: SnapshotPolicy;
+    logger?: Logger;
+}
+/**
+ * Schedules snapshots by quiet period and maximum delay per asset.
+ *
+ * Snapshots append events; the projector performs the physical write.
+ */
+export declare class SnapshotScheduler {
+    #private;
+    constructor(options: SnapshotSchedulerOptions);
+    get pending(): number;
+    start(): void;
+    close(): Promise<void>;
+    schedule(assetId: string): void;
+    flush(assetId?: string): Promise<void>;
+    snapshot(assetId: string): Promise<boolean>;
+}
+//# sourceMappingURL=SnapshotScheduler.d.ts.map

package/dist/sync/SnapshotScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotScheduler.d.ts","sourceRoot":"","sources":["../../src/sync/SnapshotScheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,UAAU,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAY1D,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,UAAU,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAC1D,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;;gBAY1B,OAAO,EAAE,wBAAwB;IAYnC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,KAAK,IAAI,IAAI;IAQP,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,QAAQ,CACN,OAAO,EAAE,MAAM,GACd,IAAI;IAmCD,KAAK,CACT,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAiBhB,QAAQ,CACN,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;CA+DpB"}

package/dist/sync/SnapshotScheduler.js

@@ -0,0 +1,136 @@
+// Import Internal Dependencies
+import { silentLogger } from "../logger.js";
+import { contentHash } from "../utils/contentHash.js";
+import { ASSET_UPDATED, encodeContent, isAssetEventType } from "../events/AssetEvents.js";
+import { TaskChain } from "../utils/TaskChain.js";
+// CONSTANTS
+const kDefaultDelay = 2_000;
+const kDefaultMaxDelay = 30_000;
+/**
+ * Schedules snapshots by quiet period and maximum delay per asset.
+ *
+ * Snapshots append events; the projector performs the physical write.
+ */
+export class SnapshotScheduler {
+    #eventStore;
+    #states;
+    #projector;
+    #policy;
+    #logger;
+    #pending = new Map();
+    #chains = new Map();
+    #unsubscribe = null;
+    constructor(options) {
+        this.#eventStore = options.eventStore;
+        this.#states = options.states;
+        this.#projector = options.projector;
+        this.#policy = {
+            delay: options.snapshot?.delay ?? kDefaultDelay,
+            maxDelay: options.snapshot?.maxDelay ?? kDefaultMaxDelay
+        };
+        this.#logger = options.logger ?? silentLogger();
+    }
+    get pending() {
+        return this.#pending.size;
+    }
+    start() {
+        this.#unsubscribe ??= this.#eventStore.subscribe((event) => {
+            if (!isAssetEventType(event.eventType)) {
+                this.schedule(event.assetId);
+            }
+        });
+    }
+    async close() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        await this.flush();
+    }
+    schedule(assetId) {
+        const entry = this.#states.get(assetId);
+        if (entry === undefined) {
+            return;
+        }
+        const policy = {
+            delay: entry.handler.snapshot?.delay ?? this.#policy.delay,
+            maxDelay: entry.handler.snapshot?.maxDelay ?? this.#policy.maxDelay
+        };
+        const pending = this.#pending.get(assetId);
+        const firstEventAt = pending?.firstEventAt ?? Date.now();
+        if (pending !== undefined) {
+            clearTimeout(pending.handle);
+        }
+        const elapsed = Date.now() - firstEventAt;
+        const delay = Math.max(0, Math.min(policy.delay, policy.maxDelay - elapsed));
+        const handle = setTimeout(() => void this.snapshot(assetId), delay);
+        handle.unref();
+        this.#pending.set(assetId, {
+            firstEventAt,
+            handle
+        });
+    }
+    async flush(assetId) {
+        const targets = assetId === undefined ?
+            [...this.#pending.keys()] :
+            [assetId].filter((id) => this.#pending.has(id));
+        for (const target of targets) {
+            await this.snapshot(target);
+        }
+        const chains = assetId === undefined ?
+            [...this.#chains.values()] :
+            [this.#chains.get(assetId)];
+        await Promise.all(chains.map((chain) => chain?.settled()));
+    }
+    snapshot(assetId) {
+        let chain = this.#chains.get(assetId);
+        if (chain === undefined) {
+            chain = new TaskChain();
+            this.#chains.set(assetId, chain);
+        }
+        return chain.run(() => this.#snapshot(assetId));
+    }
+    async #snapshot(assetId) {
+        const pending = this.#pending.get(assetId);
+        if (pending !== undefined) {
+            clearTimeout(pending.handle);
+            this.#pending.delete(assetId);
+        }
+        const entry = this.#states.get(assetId);
+        const desired = this.#projector.desired(assetId);
+        if (entry === undefined || desired === null) {
+            return false;
+        }
+        const data = await entry.handler.serialize(entry.state);
+        const hash = contentHash(data);
+        if (hash === desired.hash) {
+            return false;
+        }
+        const eventData = {
+            path: desired.path,
+            kind: desired.kind,
+            hash,
+            size: data.byteLength,
+            content: encodeContent(data)
+        };
+        const appended = this.#eventStore.writer.append({
+            assetType: entry.kind,
+            assetId,
+            eventType: ASSET_UPDATED,
+            eventData,
+            actor: {
+                type: "system",
+                source: "snapshot"
+            }
+        });
+        if (!appended.ok) {
+            this.#logger
+                .withMetadata({
+                assetId,
+                reason: appended.val.message
+            })
+                .error("asset snapshot failed");
+            return false;
+        }
+        await this.#projector.flush(assetId);
+        return true;
+    }
+}