@jolly-pixel/asset-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JollyPixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+<h1 align="center">
+  asset-server
+</h1>
+
+<p align="center">
+  Server-side asset storage, synchronization and catalog delivery
+</p>
+
+## 💃 Getting Started
+
+Install the package with npm:
+
+```bash
+$ npm i @jolly-pixel/asset-server
+```
+
+`@jolly-pixel/asset-server` runs on the server. Browser code should use
+[`@jolly-pixel/asset`](../asset) for asset records and catalogs.
+Physical storage providers are supplied by
+[`@jolly-pixel/asset-source`](../asset-source).
+
+## 👀 Usage example
+
+```ts
+import * as EventStore from "@jolly-pixel/event-store";
+import { FilesystemAssetSource } from "@jolly-pixel/asset-source";
+import { Server } from "@jolly-pixel/network";
+import {
+  createAssetBackend,
+  textureAssetHandler
+} from "@jolly-pixel/asset-server";
+
+using eventStore = await EventStore.persistence.sqlite(
+  "./assets/.jollypixel/events.db"
+);
+
+await using backend = await createAssetBackend({
+  source: new FilesystemAssetSource("./assets"),
+  eventStore,
+  handlers: [textureAssetHandler()]
+});
+
+await using server = new Server({ eventStore });
+backend.attach(server);
+```
+
+On startup, the backend catalogs files already present in `./assets`. Changes
+made through `backend.writer` are appended to the event store and written to
+the asset source. Changes made by external tools are detected and appended as
+system events.
+
+## 📚 API
+
+- [`AssetBackend`](./docs/AssetBackend.md): setup, options and lifecycle
+- [`AssetWriter`](./docs/AssetWriter.md): create, update, rename and remove assets
+- [`AssetSource`](../asset-source/docs/AssetSource.md): in-memory and
+  filesystem storage
+- [`Asset kinds`](./docs/AssetKinds.md): custom state, serialization and editing rooms
+- [`Catalog`](./docs/Catalog.md): catalog projection, network messages and HTTP access
+- [`Rooms`](./docs/Rooms.md): dynamic editing rooms and eviction
+- [`Sync`](./docs/Sync.md): lifecycle events, snapshots and reconciliation
+
+## ✨ Contributors guide
+
+Read the [contributing guide][contributing] before submitting a change.
+
+Run these commands from the monorepo root:
+
+```bash
+$ npm run test -w @jolly-pixel/asset-server
+$ npm run lint
+```
+
+> [!CAUTION]
+> Include tests when adding a feature or fixing a bug.
+
+## 📃 License
+
+MIT
+
+<!-- Reference-style links -->
+
+[contributing]: ../../CONTRIBUTING.md

package/dist/catalog/CatalogExtension.d.ts

@@ -0,0 +1,37 @@
+import { Extension, type ClientHandle, type MessageProtocols, type PeerMetadata, type RoomContext } from "@jolly-pixel/network";
+import type { AssetManifestData } from "@jolly-pixel/asset";
+import type { CatalogChange, CatalogProjection } from "./CatalogProjection.ts";
+export declare const CATALOG_ROOM = "asset-catalog";
+export declare const CATALOG_SNAPSHOT = "catalog:snapshot";
+export declare const CATALOG_CHANGED = "catalog:changed";
+export type CatalogMessage = {
+    type: typeof CATALOG_SNAPSHOT;
+    manifest: AssetManifestData;
+} | {
+    type: typeof CATALOG_CHANGED;
+    change: CatalogChange;
+};
+export declare const catalogProtocols: MessageProtocols;
+export interface CatalogExtensionOptions {
+    projection: CatalogProjection;
+    /**
+     * Room name clients join to follow the catalog.
+     * @default CATALOG_ROOM
+     */
+    id?: string;
+}
+/**
+ * Broadcasts the projected catalog without owning domain state.
+ */
+export declare class CatalogExtension extends Extension {
+    #private;
+    readonly id: string;
+    readonly name = "asset-catalog";
+    readonly protocols: MessageProtocols;
+    constructor(options: CatalogExtensionOptions);
+    onClientConnect(client: ClientHandle, _identity: PeerMetadata, context: RoomContext): void;
+    onClientDisconnect(clientId: string): void;
+    onMessage(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=CatalogExtension.d.ts.map

package/dist/catalog/CatalogExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CatalogExtension.d.ts","sourceRoot":"","sources":["../../src/catalog/CatalogExtension.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,SAAS,EAET,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAEjB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,gBAAgB,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAC;CAAE,GAC/D;IAAE,IAAI,EAAE,OAAO,eAAe,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;CAAE,CAAC;AAE7D,eAAO,MAAM,gBAAgB,EAAE,gBA+B9B,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,SAAS;;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,mBAAgB;IAC7B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAoB;gBAQtD,OAAO,EAAE,uBAAuB;IAelC,eAAe,CACb,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,WAAW,GACnB,IAAI;IAUP,kBAAkB,CAChB,QAAQ,EAAE,MAAM,GACf,IAAI;IAOP,SAAS,IAAI,IAAI;IAIR,OAAO,IAAI,IAAI;CAQzB"}

package/dist/catalog/CatalogExtension.js

@@ -0,0 +1,82 @@
+// Import Third-party Dependencies
+import { defineMessageProtocol, Extension, NO_MESSAGES } from "@jolly-pixel/network";
+// CONSTANTS
+export const CATALOG_ROOM = "asset-catalog";
+export const CATALOG_SNAPSHOT = "catalog:snapshot";
+export const CATALOG_CHANGED = "catalog:changed";
+export const catalogProtocols = {
+    inbound: NO_MESSAGES,
+    outbound: defineMessageProtocol({
+        discriminator: "type",
+        schema: {
+            oneOf: [
+                {
+                    type: "object",
+                    properties: {
+                        type: { const: CATALOG_SNAPSHOT },
+                        manifest: { type: "object" }
+                    },
+                    required: [
+                        "type",
+                        "manifest"
+                    ]
+                },
+                {
+                    type: "object",
+                    properties: {
+                        type: { const: CATALOG_CHANGED },
+                        change: { type: "object" }
+                    },
+                    required: [
+                        "type",
+                        "change"
+                    ]
+                }
+            ]
+        }
+    })
+};
+/**
+ * Broadcasts the projected catalog without owning domain state.
+ */
+export class CatalogExtension extends Extension {
+    id;
+    name = CATALOG_ROOM;
+    protocols = catalogProtocols;
+    #projection;
+    #broadcast = null;
+    #members = new Set();
+    #onChanged;
+    constructor(options) {
+        super();
+        this.id = options.id ?? CATALOG_ROOM;
+        this.#projection = options.projection;
+        this.#onChanged = (change) => this.#broadcast?.broadcast({
+            type: CATALOG_CHANGED,
+            change
+        });
+        this.#projection.on("changed", this.#onChanged);
+    }
+    onClientConnect(client, _identity, context) {
+        this.#broadcast = context.room;
+        this.#members.add(client.id);
+        context.room.sendTo(client.id, {
+            type: CATALOG_SNAPSHOT,
+            manifest: this.#projection.snapshot()
+        });
+    }
+    onClientDisconnect(clientId) {
+        this.#members.delete(clientId);
+        if (this.#members.size === 0) {
+            this.#broadcast = null;
+        }
+    }
+    onMessage() {
+        return void 0;
+    }
+    dispose() {
+        this.#projection.off("changed", this.#onChanged);
+        this.#members.clear();
+        this.#broadcast = null;
+    }
+}

package/dist/catalog/CatalogIdentitySidecar.d.ts

@@ -0,0 +1,52 @@
+import { type Infer } from "ata-validator";
+import { type AssetSource } from "@jolly-pixel/asset-source";
+import { type Logger } from "../logger.ts";
+declare const kEntrySchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly path: {
+            readonly type: "string";
+        };
+        readonly kind: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["id", "path", "kind"];
+};
+export type IdentityEntry = Readonly<Infer<typeof kEntrySchema>>;
+export interface CatalogIdentitySidecarParse {
+    readonly sidecar: CatalogIdentitySidecar;
+    readonly dropped: number;
+}
+export interface CatalogIdentitySidecarData {
+    readonly version: 1;
+    readonly assets: readonly IdentityEntry[];
+}
+/**
+ * Persists path-to-AssetId mappings beside the workspace.
+ *
+ * The committed half of the catalog: {@link CatalogProjection} is replayed
+ * from the event log and can always be rebuilt, while this file is the only
+ * record that survives a clone, since the log itself is never committed.
+ *
+ * An unreadable sidecar loses ids, not event data.
+ */
+export declare class CatalogIdentitySidecar {
+    #private;
+    constructor(entries?: Iterable<IdentityEntry>);
+    get size(): number;
+    set(entry: IdentityEntry): this;
+    removeById(id: string): boolean;
+    byPath(path: string): IdentityEntry | undefined;
+    byId(id: string): IdentityEntry | undefined;
+    [Symbol.iterator](): IterableIterator<IdentityEntry>;
+    toJSON(): CatalogIdentitySidecarData;
+    save(source: AssetSource): Promise<void>;
+    static load(source: AssetSource, logger?: Logger): Promise<CatalogIdentitySidecar>;
+    static parse(input: unknown): CatalogIdentitySidecarParse;
+}
+export {};
+//# sourceMappingURL=CatalogIdentitySidecar.d.ts.map

package/dist/catalog/CatalogIdentitySidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CatalogIdentitySidecar.d.ts","sourceRoot":"","sources":["../../src/catalog/CatalogIdentitySidecar.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AAMtB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;CAYhB,CAAC;AAaH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAsB;;gBAK/B,OAAO,GAAE,QAAQ,CAAC,aAAa,CAAM;IAOvC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CACD,KAAK,EAAE,aAAa,GACnB,IAAI;IAsBP,UAAU,CACR,EAAE,EAAE,MAAM,GACT,OAAO;IAYV,MAAM,CACJ,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,SAAS;IAI5B,IAAI,CACF,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS;IAI5B,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAIpD,MAAM,IAAI,0BAA0B;IASpC,IAAI,CACF,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC;WAQH,IAAI,CACf,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,MAAuB,GAC9B,OAAO,CAAC,sBAAsB,CAAC;IAmBlC,MAAM,CAAC,KAAK,CACV,KAAK,EAAE,OAAO,GACb,2BAA2B;CA2B/B"}

package/dist/catalog/CatalogIdentitySidecar.js

@@ -0,0 +1,132 @@
+// 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 { IDENTITY_SIDECAR_PATH } from "../constants.js";
+// CONSTANTS
+const kSidecarVersion = 1;
+const kValidatorOptions = { useDefaults: false };
+const kEntrySchema = defineSchema({
+    type: "object",
+    properties: {
+        id: { type: "string" },
+        path: { type: "string" },
+        kind: { type: "string" }
+    },
+    required: [
+        "id",
+        "path",
+        "kind"
+    ]
+});
+const kEntryValidator = new Validator(kEntrySchema, kValidatorOptions);
+const kDocumentValidator = new Validator(defineSchema({
+    type: "object",
+    properties: {
+        assets: { type: "array" }
+    },
+    required: ["assets"]
+}), kValidatorOptions);
+/**
+ * Persists path-to-AssetId mappings beside the workspace.
+ *
+ * The committed half of the catalog: {@link CatalogProjection} is replayed
+ * from the event log and can always be rebuilt, while this file is the only
+ * record that survives a clone, since the log itself is never committed.
+ *
+ * An unreadable sidecar loses ids, not event data.
+ */
+export class CatalogIdentitySidecar {
+    #byPath = new Map();
+    #byId = new Map();
+    constructor(entries = []) {
+        for (const entry of entries) {
+            this.set(entry);
+        }
+    }
+    get size() {
+        return this.#byPath.size;
+    }
+    set(entry) {
+        const previousPath = this.#byId.get(entry.id);
+        if (previousPath !== undefined) {
+            this.#byPath.delete(previousPath.path);
+        }
+        const previousId = this.#byPath.get(entry.path);
+        if (previousId !== undefined) {
+            this.#byId.delete(previousId.id);
+        }
+        const stored = {
+            id: entry.id,
+            path: entry.path,
+            kind: entry.kind
+        };
+        this.#byPath.set(stored.path, stored);
+        this.#byId.set(stored.id, stored);
+        return this;
+    }
+    removeById(id) {
+        const entry = this.#byId.get(id);
+        if (entry === undefined) {
+            return false;
+        }
+        this.#byId.delete(id);
+        this.#byPath.delete(entry.path);
+        return true;
+    }
+    byPath(path) {
+        return this.#byPath.get(path);
+    }
+    byId(id) {
+        return this.#byId.get(id);
+    }
+    [Symbol.iterator]() {
+        return this.#byId.values();
+    }
+    toJSON() {
+        return {
+            version: kSidecarVersion,
+            assets: [...this.#byId.values()].sort((a, b) => a.path.localeCompare(b.path))
+        };
+    }
+    save(source) {
+        return writeJsonFile(source, IDENTITY_SIDECAR_PATH, this.toJSON());
+    }
+    static async load(source, logger = silentLogger()) {
+        const { sidecar, dropped } = CatalogIdentitySidecar.parse(await readJsonFile(source, IDENTITY_SIDECAR_PATH));
+        if (dropped > 0) {
+            logger
+                .withMetadata({
+                path: IDENTITY_SIDECAR_PATH,
+                dropped
+            })
+                .warn("identity sidecar entries dropped");
+        }
+        return sidecar;
+    }
+    static parse(input) {
+        const document = kDocumentValidator.validate(input);
+        if (!document.valid) {
+            return {
+                sidecar: new CatalogIdentitySidecar(),
+                dropped: 0
+            };
+        }
+        const entries = [];
+        let dropped = 0;
+        for (const asset of document.data.assets) {
+            const entry = kEntryValidator.validate(asset);
+            if (entry.valid) {
+                entries.push(entry.data);
+            }
+            else {
+                dropped += 1;
+            }
+        }
+        return {
+            sidecar: new CatalogIdentitySidecar(entries),
+            dropped
+        };
+    }
+}

package/dist/catalog/CatalogProjection.d.ts

@@ -0,0 +1,32 @@
+import type * as EventStore from "@jolly-pixel/event-store";
+import { AssetCatalog, type AssetManifestData, type AssetRecordData } from "@jolly-pixel/asset";
+import { Emitter } from "@openally/emitt";
+export interface CatalogChange {
+    readonly eventType: string;
+    readonly assetId: string;
+    /**
+     * The record after the change, or `null` when the asset was removed.
+     */
+    readonly record: AssetRecordData | null;
+}
+export type CatalogProjectionEventMap = {
+    changed: (change: CatalogChange) => void;
+};
+export interface CatalogProjectionOptions {
+    eventStore: EventStore.EventStore;
+}
+/**
+ * Projects lifecycle events into catalog records keyed by asset id.
+ */
+export declare class CatalogProjection extends Emitter<CatalogProjectionEventMap> {
+    #private;
+    constructor(options: CatalogProjectionOptions);
+    get catalog(): AssetCatalog;
+    get size(): number;
+    load(): void;
+    start(): void;
+    close(): void;
+    apply(event: EventStore.Event): boolean;
+    snapshot(): AssetManifestData;
+}
+//# sourceMappingURL=CatalogProjection.d.ts.map

package/dist/catalog/CatalogProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CatalogProjection.d.ts","sourceRoot":"","sources":["../../src/catalog/CatalogProjection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,UAAU,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EACL,YAAY,EAGZ,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAc1C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,CACP,MAAM,EAAE,aAAa,KAClB,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,OAAO,CAC5C,yBAAyB,CAC1B;;gBAMG,OAAO,EAAE,wBAAwB;IAMnC,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI;IAWZ,KAAK,IAAI,IAAI;IAOb,KAAK,IAAI,IAAI;IAMb,KAAK,CACH,KAAK,EAAE,UAAU,CAAC,KAAK,GACtB,OAAO;IAgBV,QAAQ,IAAI,iBAAiB;CAqE9B"}

package/dist/catalog/CatalogProjection.js

@@ -0,0 +1,109 @@
+import { AssetCatalog, AssetId, AssetRecord } from "@jolly-pixel/asset";
+import { Emitter } from "@openally/emitt";
+// Import Internal Dependencies
+import { ASSET_EVENT_PREFIX } from "../constants.js";
+import { ASSET_CHECKPOINT_EVENT_TYPES, ASSET_CREATED, ASSET_DELETED, ASSET_RENAMED, ASSET_UPDATED, parseAssetEvent } from "../events/AssetEvents.js";
+/**
+ * Projects lifecycle events into catalog records keyed by asset id.
+ */
+export class CatalogProjection extends Emitter {
+    #eventStore;
+    #catalog = new AssetCatalog();
+    #unsubscribe = null;
+    constructor(options) {
+        super();
+        this.#eventStore = options.eventStore;
+    }
+    get catalog() {
+        return this.#catalog;
+    }
+    get size() {
+        return this.#catalog.size;
+    }
+    load() {
+        this.#catalog = new AssetCatalog();
+        const events = this.#eventStore.reader.listFromCheckpoints({
+            checkpointEventTypes: ASSET_CHECKPOINT_EVENT_TYPES,
+            eventTypePrefix: ASSET_EVENT_PREFIX
+        });
+        for (const event of events) {
+            this.apply(event);
+        }
+    }
+    start() {
+        this.#unsubscribe ??= this.#eventStore.subscribe((event) => void this.apply(event), { eventTypePrefix: ASSET_EVENT_PREFIX });
+    }
+    close() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        this.removeAllListeners();
+    }
+    apply(event) {
+        const parsed = parseAssetEvent(event);
+        if (!parsed.ok) {
+            return false;
+        }
+        const change = this.#fold(parsed.val);
+        if (change === null) {
+            return false;
+        }
+        this.emit("changed", change);
+        return true;
+    }
+    snapshot() {
+        return this.#catalog.toJSON();
+    }
+    #fold(event) {
+        const id = new AssetId(event.assetId);
+        switch (event.eventType) {
+            case ASSET_CREATED:
+            case ASSET_UPDATED: {
+                const data = event.eventData;
+                return this.#upsert(new AssetRecord({
+                    id,
+                    kind: data.kind,
+                    source: data.path,
+                    revision: data.hash
+                }), event.eventType);
+            }
+            case ASSET_RENAMED: {
+                const data = event.eventData;
+                const previous = this.#catalog.has(id) ?
+                    this.#catalog.get(id) :
+                    null;
+                return this.#upsert(new AssetRecord({
+                    id,
+                    kind: previous?.kind ?? data.kind,
+                    source: data.to,
+                    revision: previous?.revision ?? data.hash
+                }), event.eventType);
+            }
+            case ASSET_DELETED: {
+                if (!this.#catalog.has(id)) {
+                    return null;
+                }
+                this.#catalog.remove(id);
+                return {
+                    eventType: event.eventType,
+                    assetId: event.assetId,
+                    record: null
+                };
+            }
+            default:
+                return null;
+        }
+    }
+    #upsert(record, eventType) {
+        if (this.#catalog.has(record.id)) {
+            this.#catalog.replace(record);
+        }
+        else {
+            this.#catalog.add(record);
+        }
+        return {
+            eventType,
+            assetId: record.id.value,
+            record: record.toJSON()
+        };
+    }
+}

package/dist/catalog/httpHandler.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { CatalogProjection } from "./CatalogProjection.ts";
+export declare const DEFAULT_CATALOG_PATH = "/__jollypixel/catalog";
+export type CatalogHandler = (request: IncomingMessage, response: ServerResponse, next: () => void) => void;
+export interface CatalogHandlerOptions {
+    projection: CatalogProjection;
+    /**
+     * @default DEFAULT_CATALOG_PATH
+     */
+    path?: string;
+}
+export declare function createCatalogHandler(options: CatalogHandlerOptions): CatalogHandler;
+//# sourceMappingURL=httpHandler.d.ts.map

package/dist/catalog/httpHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpHandler.d.ts","sourceRoot":"","sources":["../../src/catalog/httpHandler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACf,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,eAAO,MAAM,oBAAoB,0BAAmB,CAAC;AAErD,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,CAAC;AAEV,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAiDhB"}

package/dist/catalog/httpHandler.js

@@ -0,0 +1,27 @@
+// Import Node.js Dependencies
+import { Buffer } from "node:buffer";
+// Import Third-party Dependencies
+import { CATALOG_URL_PATH } from "@jolly-pixel/asset";
+export const DEFAULT_CATALOG_PATH = CATALOG_URL_PATH;
+export function createCatalogHandler(options) {
+    const { projection, path = DEFAULT_CATALOG_PATH } = options;
+    return function catalogHandler(request, response, next) {
+        const requestUrl = URL.parse(request.url ?? "", "http://localhost");
+        if (requestUrl?.pathname !== path) {
+            next();
+            return;
+        }
+        if (request.method !== "GET" &&
+            request.method !== "HEAD") {
+            response.statusCode = 405;
+            response.setHeader("allow", "GET, HEAD");
+            response.end();
+            return;
+        }
+        const payload = JSON.stringify(projection.snapshot());
+        response.statusCode = 200;
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("content-length", String(Buffer.byteLength(payload)));
+        response.end(request.method === "HEAD" ? undefined : payload);
+    };
+}

package/dist/catalog/index.d.ts

@@ -0,0 +1,9 @@
+export { CatalogIdentitySidecar } from "./CatalogIdentitySidecar.ts";
+export type { CatalogIdentitySidecarData, IdentityEntry } from "./CatalogIdentitySidecar.ts";
+export { CatalogProjection } from "./CatalogProjection.ts";
+export type { CatalogChange, CatalogProjectionEventMap, CatalogProjectionOptions } from "./CatalogProjection.ts";
+export { CatalogExtension, CATALOG_CHANGED, CATALOG_ROOM, CATALOG_SNAPSHOT } from "./CatalogExtension.ts";
+export type { CatalogExtensionOptions, CatalogMessage } from "./CatalogExtension.ts";
+export { createCatalogHandler, DEFAULT_CATALOG_PATH } from "./httpHandler.ts";
+export type { CatalogHandler, CatalogHandlerOptions } from "./httpHandler.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/catalog/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EACV,0BAA0B,EAC1B,aAAa,EACd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,uBAAuB,EACvB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,kBAAkB,CAAC"}

package/dist/catalog/index.js

@@ -0,0 +1,4 @@
+export { CatalogIdentitySidecar } from "./CatalogIdentitySidecar.js";
+export { CatalogProjection } from "./CatalogProjection.js";
+export { CatalogExtension, CATALOG_CHANGED, CATALOG_ROOM, CATALOG_SNAPSHOT } from "./CatalogExtension.js";
+export { createCatalogHandler, DEFAULT_CATALOG_PATH } from "./httpHandler.js";

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+import { STATE_DIRECTORY } from "@jolly-pixel/asset-source";
+export { STATE_DIRECTORY };
+export declare const IDENTITY_SIDECAR_PATH = ".jollypixel/assets.json";
+export declare const PROJECTION_STATE_PATH = ".jollypixel/state.json";
+export declare const STATE_GITIGNORE_PATH = ".jollypixel/.gitignore";
+export declare const EVENTS_DB_PATH = ".jollypixel/events.db";
+export declare const STATE_GITIGNORE_CONTENT = "state.json\nevents.db\nevents.db-journal\nevents.db-wal\n";
+export declare const ASSET_EVENT_PREFIX = "asset.";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,eAAO,MAAM,qBAAqB,4BAAmC,CAAC;AACtE,eAAO,MAAM,qBAAqB,2BAAkC,CAAC;AACrE,eAAO,MAAM,oBAAoB,2BAAkC,CAAC;AACpE,eAAO,MAAM,cAAc,0BAAiC,CAAC;AAE7D,eAAO,MAAM,uBAAuB,8DAInC,CAAC;AAEF,eAAO,MAAM,kBAAkB,WAAW,CAAC"}

package/dist/constants.js

@@ -0,0 +1,13 @@
+// Import Third-party Dependencies
+import { STATE_DIRECTORY } from "@jolly-pixel/asset-source";
+export { STATE_DIRECTORY };
+export const IDENTITY_SIDECAR_PATH = `${STATE_DIRECTORY}/assets.json`;
+export const PROJECTION_STATE_PATH = `${STATE_DIRECTORY}/state.json`;
+export const STATE_GITIGNORE_PATH = `${STATE_DIRECTORY}/.gitignore`;
+export const EVENTS_DB_PATH = `${STATE_DIRECTORY}/events.db`;
+export const STATE_GITIGNORE_CONTENT = `state.json
+events.db
+events.db-journal
+events.db-wal
+`;
+export const ASSET_EVENT_PREFIX = "asset.";