@jolly-pixel/asset-server 1.0.0 → 2.0.0

package/docs/AssetKinds.md

@@ -1,204 +1,204 @@
-# Asset kinds
-
-An `AssetKindHandler` defines how one asset type is recognized, folded into
-state and serialized.
-
-```ts
-interface AssetKindHandler<TState = unknown, TCommand = unknown> {
-  readonly kind: string;
-  readonly match: readonly string[];
-  readonly snapshot?: SnapshotPolicy;
-
-  create(assetId: string): TState;
-  apply(state: TState, event: Event): void;
-  serialize(state: TState): Promise<Uint8Array>;
-  live?(binding: AssetRoomBinding<TState>): AssetLiveProtocol<TCommand>;
-  createExtension?(binding: AssetRoomBinding<TState>): Extension;
-}
-```
-
-Handlers are checked in registration order. `match` contains globs matched
-against root-relative POSIX paths. The built-in `binary` handler receives any
-path that no registered handler claims.
-
-`apply` receives lifecycle events and domain events from the asset stream.
-`serialize` returns the bytes stored by the asset source. A handler that
-supports live editing provides `live`; other kinds have no dynamic editing
-room.
-
-`apply` must reset the existing `TState` in place for `asset.created`,
-`asset.updated` and `asset.deleted`. Each event is a complete checkpoint.
-Replay creates a fresh state, resumes at the newest checkpoint and folds later
-events. Reassigning the `state` parameter has no effect because `apply` returns
-`void` and the store retains the value returned by `create`.
-
-`TState` defaults to `unknown`, so a handler declared without it must narrow
-its own state before use. Pass the state type to keep `create`, `apply` and
-`serialize` checked against each other.
-
-## Reading lifecycle payloads
-
-`event.eventData` is typed `unknown` by the event store, because the store
-holds any domain. Parse it with `parseAssetEvent` rather than asserting a
-shape: it validates the payload against a JSON Schema for its event type and
-returns a `Result` carrying the parsed event, or the reason it was refused.
-
-```ts
-apply(state: MyState, event: Event): void {
-  const parsed = parseAssetEvent(event);
-  if (parsed.ok && parsed.val.eventType === ASSET_UPDATED) {
-    // eventData is AssetWriteData here
-    state.bytes = decodeContent(parsed.val.eventData.content);
-  }
-}
-```
-
-Payloads read straight from persistence are parsed JSON, so a corrupt row
-would otherwise reach the fold unchecked.
-
-## Snapshot policy
-
-```ts
-interface SnapshotPolicy {
-  delay?: number;
-  maxDelay?: number;
-}
-```
-
-`delay` is the quiet period after the latest domain event. `maxDelay` limits
-the time since the first unsnapshotted event. Backend defaults are `2_000` ms
-and `30_000` ms. A handler can override either value through `snapshot`.
-
-`delay: 0` schedules the snapshot for the next timer turn. Lifecycle events
-do not schedule snapshots.
-
-## Registry
-
-```ts
-const kinds = new AssetKindRegistry([pixelArtHandler]);
-
-kinds.register(voxelHandler);
-kinds.resolve("textures/grass.png");
-kinds.get("pixelart");
-```
-
-Registering the same kind twice throws. The reserved `binary` fallback cannot
-be replaced.
-
-## Built-in kinds
-
-`binary` is the reserved fallback. `texture` is a shipped handler that claims
-image files so a runtime `AssetType` of the same name can resolve them:
-
-```ts
-import { textureAssetHandler } from "@jolly-pixel/asset-server";
-
-const kinds = new AssetKindRegistry([textureAssetHandler()]);
-```
-
-Its state is the file's bytes, exactly like `binary`, and it has no `live`
-protocol, so texture assets get no editing room. The kind exists to
-name the record: `AssetCatalog.resolve()` rejects a record whose kind does not
-match its reference, and nothing on the browser side loads `binary`. Pass
-`match` to narrow the globs from the default image extensions.
-
-## Kinds shipped by other packages
-
-Two handlers live with the domain they serialize rather than here, because
-asset-server does not depend on the renderers:
-
-```ts
-import { pixelArtAssetHandler } from "@jolly-pixel/pixel-draw.renderer/asset/index.ts";
-import { voxelMapAssetHandler } from "@jolly-pixel/voxel.renderer/asset/index.ts";
-
-await createAssetBackend({
-  source,
-  eventStore,
-  handlers: [
-    pixelArtAssetHandler(),
-    voxelMapAssetHandler(),
-    textureAssetHandler()
-  ]
-});
-```
-
-Both take `@jolly-pixel/asset-server` as an optional peer dependency, so a
-browser-only consumer of either renderer never installs it.
-
-## Writing an editable kind
-
-A kind with live editing has two halves that must not overlap: `apply` is the
-only writer of state, and `live` describes a room that appends without
-writing. `AssetRoomExtension` hosts the protocol, so a kind supplies only
-what is specific to it:
-
-```ts
-interface AssetLiveProtocol<TCommand = unknown> {
-  readonly commandEventType: string;
-  readonly actions: readonly string[];
-
-  parse(payload: unknown): TCommand | null;
-  snapshot(): unknown;
-  arbitrate(
-    command: TCommand,
-    clientId: string
-  ): AssetArbitration<TCommand> | null;
-  broadcast?(command: TCommand): AssetRoomMessage;
-}
-```
-
-`live` runs once per room, so per-room state such as a conflict tracker
-belongs in the returned protocol rather than in the handler:
-
-```ts
-live(binding) {
-  const arbiter = new MyArbiter({ conflictResolver });
-  const { state } = binding;
-
-  return {
-    commandEventType: MY_COMMAND,
-    actions: MY_ACTIONS,
-    parse: (payload) => isMyCommand(payload) ? payload : null,
-    snapshot: () => state.toJSON(),
-    arbitrate(command, clientId) {
-      const admitted = arbiter.admit(command);
-      if (admitted === null) {
-        return null;
-      }
-
-      return {
-        command: admitted,
-        commit: () => arbiter.record(admitted)
-      };
-    }
-  };
-}
-```
-
-The room parses the payload, arbitrates it, appends
-`arbitration.command` under `commandEventType`, then calls
-`arbitration.commit` and broadcasts. `commit` runs only after the append
-lands, so a conflict tracker never records a command the store refused. The
-append folds through `apply` before it resolves, so state is current by the
-time peers hear about the change.
-
-`broadcast` overrides the default `{ type: "command", data: command }`
-envelope. `voxel-map` uses it to answer a `world-replace` with a full
-snapshot.
-
-`actions` names the commands the kind accepts. A configured rights table
-checks each message under `${kind}.${action}`; a payload naming no declared
-action is checked under `${kind}.invalid`.
-
-A room that also mutated the state would apply every command twice: once
-itself and once through the fold. Absolute writes survive that, but a command
-carrying a delta does not. `voxel-map`'s `offset-updated` is exactly such a
-command, which is why both shipped kinds keep the halves separate.
-
-`createExtension` remains as an escape hatch for a room protocol `live`
-cannot express, and takes precedence over it. It returns a `network.Extension`
-whose `id` must equal the room name.
-
-`apply` must never throw. Its event is already persisted, so a fold that
-aborts would break every later replay. Both shipped handlers catch, log and
-keep the last good state.
+# Asset kinds
+
+An `AssetKindHandler` defines how one asset type is recognized, folded into
+state and serialized.
+
+```ts
+interface AssetKindHandler<TState = unknown, TCommand = unknown> {
+  readonly kind: string;
+  readonly match: readonly string[];
+  readonly snapshot?: SnapshotPolicy;
+
+  create(assetId: string): TState;
+  apply(state: TState, event: Event): void;
+  serialize(state: TState): Promise<Uint8Array>;
+  live?(binding: AssetRoomBinding<TState>): AssetLiveProtocol<TCommand>;
+  createExtension?(binding: AssetRoomBinding<TState>): Extension;
+}
+```
+
+Handlers are checked in registration order. `match` contains globs matched
+against root-relative POSIX paths. The built-in `binary` handler receives any
+path that no registered handler claims.
+
+`apply` receives lifecycle events and domain events from the asset stream.
+`serialize` returns the bytes stored by the asset source. A handler that
+supports live editing provides `live`; other kinds have no dynamic editing
+room.
+
+`apply` must reset the existing `TState` in place for `asset.created`,
+`asset.updated` and `asset.deleted`. Each event is a complete checkpoint.
+Replay creates a fresh state, resumes at the newest checkpoint and folds later
+events. Reassigning the `state` parameter has no effect because `apply` returns
+`void` and the store retains the value returned by `create`.
+
+`TState` defaults to `unknown`, so a handler declared without it must narrow
+its own state before use. Pass the state type to keep `create`, `apply` and
+`serialize` checked against each other.
+
+## Reading lifecycle payloads
+
+`event.eventData` is typed `unknown` by the event store, because the store
+holds any domain. Parse it with `parseAssetEvent` rather than asserting a
+shape: it validates the payload against a JSON Schema for its event type and
+returns a `Result` carrying the parsed event, or the reason it was refused.
+
+```ts
+apply(state: MyState, event: Event): void {
+  const parsed = parseAssetEvent(event);
+  if (parsed.ok && parsed.val.eventType === ASSET_UPDATED) {
+    // eventData is AssetWriteData here
+    state.bytes = decodeContent(parsed.val.eventData.content);
+  }
+}
+```
+
+Payloads read straight from persistence are parsed JSON, so a corrupt row
+would otherwise reach the fold unchecked.
+
+## Snapshot policy
+
+```ts
+interface SnapshotPolicy {
+  delay?: number;
+  maxDelay?: number;
+}
+```
+
+`delay` is the quiet period after the latest domain event. `maxDelay` limits
+the time since the first unsnapshotted event. Backend defaults are `2_000` ms
+and `30_000` ms. A handler can override either value through `snapshot`.
+
+`delay: 0` schedules the snapshot for the next timer turn. Lifecycle events
+do not schedule snapshots.
+
+## Registry
+
+```ts
+const kinds = new AssetKindRegistry([pixelArtHandler]);
+
+kinds.register(voxelHandler);
+kinds.resolve("textures/grass.png");
+kinds.get("pixelart");
+```
+
+Registering the same kind twice throws. The reserved `binary` fallback cannot
+be replaced.
+
+## Built-in kinds
+
+`binary` is the reserved fallback. `texture` is a shipped handler that claims
+image files so a runtime `AssetType` of the same name can resolve them:
+
+```ts
+import { textureAssetHandler } from "@jolly-pixel/asset-server";
+
+const kinds = new AssetKindRegistry([textureAssetHandler()]);
+```
+
+Its state is the file's bytes, exactly like `binary`, and it has no `live`
+protocol, so texture assets get no editing room. The kind exists to
+name the record: `AssetCatalog.resolve()` rejects a record whose kind does not
+match its reference, and nothing on the browser side loads `binary`. Pass
+`match` to narrow the globs from the default image extensions.
+
+## Kinds shipped by other packages
+
+Two handlers live with the domain they serialize rather than here, because
+asset-server does not depend on the renderers:
+
+```ts
+import { pixelArtAssetHandler } from "@jolly-pixel/pixel-draw.renderer/asset/index.ts";
+import { voxelMapAssetHandler } from "@jolly-pixel/voxel.renderer/asset/index.ts";
+
+await createAssetBackend({
+  source,
+  eventStore,
+  handlers: [
+    pixelArtAssetHandler(),
+    voxelMapAssetHandler(),
+    textureAssetHandler()
+  ]
+});
+```
+
+Both take `@jolly-pixel/asset-server` as an optional peer dependency, so a
+browser-only consumer of either renderer never installs it.
+
+## Writing an editable kind
+
+A kind with live editing has two halves that must not overlap: `apply` is the
+only writer of state, and `live` describes a room that appends without
+writing. `AssetRoomExtension` hosts the protocol, so a kind supplies only
+what is specific to it:
+
+```ts
+interface AssetLiveProtocol<TCommand = unknown> {
+  readonly commandEventType: string;
+  readonly actions: readonly string[];
+
+  parse(payload: unknown): TCommand | null;
+  snapshot(): unknown;
+  arbitrate(
+    command: TCommand,
+    clientId: string
+  ): AssetArbitration<TCommand> | null;
+  broadcast?(command: TCommand): AssetRoomMessage;
+}
+```
+
+`live` runs once per room, so per-room state such as a conflict tracker
+belongs in the returned protocol rather than in the handler:
+
+```ts
+live(binding) {
+  const arbiter = new MyArbiter({ conflictResolver });
+  const { state } = binding;
+
+  return {
+    commandEventType: MY_COMMAND,
+    actions: MY_ACTIONS,
+    parse: (payload) => isMyCommand(payload) ? payload : null,
+    snapshot: () => state.toJSON(),
+    arbitrate(command, clientId) {
+      const admitted = arbiter.admit(command);
+      if (admitted === null) {
+        return null;
+      }
+
+      return {
+        command: admitted,
+        commit: () => arbiter.record(admitted)
+      };
+    }
+  };
+}
+```
+
+The room parses the payload, arbitrates it, appends
+`arbitration.command` under `commandEventType`, then calls
+`arbitration.commit` and broadcasts. `commit` runs only after the append
+lands, so a conflict tracker never records a command the store refused. The
+append folds through `apply` before it resolves, so state is current by the
+time peers hear about the change.
+
+`broadcast` overrides the default `{ type: "command", data: command }`
+envelope. `voxel-map` uses it to answer a `world-replace` with a full
+snapshot.
+
+`actions` names the commands the kind accepts. A configured rights table
+checks each message under `${kind}.${action}`; a payload naming no declared
+action is checked under `${kind}.invalid`.
+
+A room that also mutated the state would apply every command twice: once
+itself and once through the fold. Absolute writes survive that, but a command
+carrying a delta does not. `voxel-map`'s `offset-updated` is exactly such a
+command, which is why both shipped kinds keep the halves separate.
+
+`createExtension` remains as an escape hatch for a room protocol `live`
+cannot express, and takes precedence over it. It returns a `network.Extension`
+whose `id` must equal the room name.
+
+`apply` must never throw. Its event is already persisted, so a fold that
+aborts would break every later replay. Both shipped handlers catch, log and
+keep the last good state.

package/docs/AssetWriter.md

@@ -1,62 +1,62 @@
-# AssetWriter
-
-Use `backend.writer` to change assets. Each method appends an asset lifecycle
-event before the backend updates the catalog and source.
-
-```ts
-writer.create(input: CreateAssetInput): Promise<Result<Event, Error>>
-writer.update(input: UpdateAssetInput): Promise<Result<Event, Error>>
-writer.rename(input: RenameAssetInput): Promise<Result<Event, Error>>
-writer.remove(input: DeleteAssetInput): Promise<Result<Event, Error>>
-```
-
-Every input requires an event-store actor:
-
-```ts
-const actor = { type: "user", id: "alice" } as const;
-```
-
-## Create
-
-```ts
-const result = await backend.writer.create({
-  path: "textures/grass.png",
-  data: pngBytes,
-  actor
-});
-
-const event = result.unwrap();
-console.log(event.assetId);
-```
-
-```ts
-interface CreateAssetInput {
-  path: string;
-  data: Uint8Array;
-  actor: Actor;
-  kind?: string;
-  assetId?: string;
-}
-```
-
-The backend generates an asset ID when `assetId` is omitted. It resolves the
-kind from the registered path globs when `kind` is omitted.
-
-## Update, rename and remove
-
-```ts
-await backend.writer.update({ assetId, data: nextBytes, actor });
-await backend.writer.rename({ assetId, to: "textures/ground.png", actor });
-await backend.writer.remove({ assetId, actor });
-```
-
-These operations return an error result when the asset ID is unknown. Paths
-are
-[root-relative POSIX paths](../../asset-source/docs/AssetSource.md#paths); one
-that escapes the
-source root, or that names the `.jollypixel/` state directory, throws
-`AssetPathEscapeError`.
-
-Call `backend.flush(assetId)` when the caller must wait for the resulting
-source write. The `alreadyProjected` input option is reserved for source-backed
-reconciliation, where the bytes already exist in the source.
+# AssetWriter
+
+Use `backend.writer` to change assets. Each method appends an asset lifecycle
+event before the backend updates the catalog and source.
+
+```ts
+writer.create(input: CreateAssetInput): Promise<Result<Event, Error>>
+writer.update(input: UpdateAssetInput): Promise<Result<Event, Error>>
+writer.rename(input: RenameAssetInput): Promise<Result<Event, Error>>
+writer.remove(input: DeleteAssetInput): Promise<Result<Event, Error>>
+```
+
+Every input requires an event-store actor:
+
+```ts
+const actor = { type: "user", id: "alice" } as const;
+```
+
+## Create
+
+```ts
+const result = await backend.writer.create({
+  path: "textures/grass.png",
+  data: pngBytes,
+  actor
+});
+
+const event = result.unwrap();
+console.log(event.assetId);
+```
+
+```ts
+interface CreateAssetInput {
+  path: string;
+  data: Uint8Array;
+  actor: Actor;
+  kind?: string;
+  assetId?: string;
+}
+```
+
+The backend generates an asset ID when `assetId` is omitted. It resolves the
+kind from the registered path globs when `kind` is omitted.
+
+## Update, rename and remove
+
+```ts
+await backend.writer.update({ assetId, data: nextBytes, actor });
+await backend.writer.rename({ assetId, to: "textures/ground.png", actor });
+await backend.writer.remove({ assetId, actor });
+```
+
+These operations return an error result when the asset ID is unknown. Paths
+are
+[root-relative POSIX paths](../../asset-source/docs/AssetSource.md#paths); one
+that escapes the
+source root, or that names the `.jollypixel/` state directory, throws
+`AssetPathEscapeError`.
+
+Call `backend.flush(assetId)` when the caller must wait for the resulting
+source write. The `alreadyProjected` input option is reserved for source-backed
+reconciliation, where the bytes already exist in the source.

package/docs/Catalog.md

@@ -1,71 +1,71 @@
-# Catalog
-
-`CatalogProjection` folds asset lifecycle events into an
-`@jolly-pixel/asset` catalog.
-
-```ts
-const projection = new CatalogProjection({ eventStore });
-projection.load();
-projection.start();
-```
-
-- `load()` folds each asset's newest lifecycle checkpoint and the events
-  after it. See [Replay](./Sync.md#replay).
-- `catalog` exposes the current `AssetCatalog`.
-- `size` is the number of cataloged assets.
-- `snapshot()` returns `AssetManifestData`.
-- `changed` is emitted for each recognized lifecycle event applied to the
-  catalog. A deleted asset has `record: null`.
-- `close()` stops following appended events and removes listeners.
-
-`apply(event)` returns `false` and changes nothing for events outside the
-`asset.` prefix and for lifecycle events whose payload does not match their
-type. See [Typed payloads](./Sync.md#typed-payloads).
-
-Each catalog record uses the asset content hash as its `revision`.
-
-## Network room
-
-`CatalogExtension` provides a read-only `asset-catalog` room. A client receives
-a snapshot when it joins and catalog changes while it remains connected.
-
-```ts
-server.register(new CatalogExtension({ projection }));
-```
-
-```ts
-{ type: "catalog:snapshot", manifest: AssetManifestData }
-{ type: "catalog:changed", change: { eventType, assetId, record } }
-```
-
-`createAssetBackend().attach(server)` registers this room for the usual setup.
-
-## HTTP handler
-
-```ts
-import { createCatalogHandler } from "@jolly-pixel/asset-server/catalog";
-
-const handler = createCatalogHandler({
-  projection,
-  path: "/__jollypixel/catalog"
-});
-```
-
-The default path is `/__jollypixel/catalog`. `GET` returns the JSON snapshot
-and `HEAD` returns the same headers without a body. Other methods on that path
-receive `405` with `Allow: GET, HEAD`. Requests for another path are passed to
-`next()`.
-
-## Vite plugin
-
-```ts
-import {
-  createAssetCatalogPlugin
-} from "@jolly-pixel/asset-server/plugins/vite.ts";
-
-export default {
-  plugins: [createAssetCatalogPlugin({ projection })]
-};
-```
-
-The plugin accepts the same optional `path` override as the HTTP handler.
+# Catalog
+
+`CatalogProjection` folds asset lifecycle events into an
+`@jolly-pixel/asset` catalog.
+
+```ts
+const projection = new CatalogProjection({ eventStore });
+projection.load();
+projection.start();
+```
+
+- `load()` folds each asset's newest lifecycle checkpoint and the events
+  after it. See [Replay](./Sync.md#replay).
+- `catalog` exposes the current `AssetCatalog`.
+- `size` is the number of cataloged assets.
+- `snapshot()` returns `AssetManifestData`.
+- `changed` is emitted for each recognized lifecycle event applied to the
+  catalog. A deleted asset has `record: null`.
+- `close()` stops following appended events and removes listeners.
+
+`apply(event)` returns `false` and changes nothing for events outside the
+`asset.` prefix and for lifecycle events whose payload does not match their
+type. See [Typed payloads](./Sync.md#typed-payloads).
+
+Each catalog record uses the asset content hash as its `revision`.
+
+## Network room
+
+`CatalogExtension` provides a read-only `asset-catalog` room. A client receives
+a snapshot when it joins and catalog changes while it remains connected.
+
+```ts
+server.register(new CatalogExtension({ projection }));
+```
+
+```ts
+{ type: "catalog:snapshot", manifest: AssetManifestData }
+{ type: "catalog:changed", change: { eventType, assetId, record } }
+```
+
+`createAssetBackend().attach(server)` registers this room for the usual setup.
+
+## HTTP handler
+
+```ts
+import { createCatalogHandler } from "@jolly-pixel/asset-server/catalog";
+
+const handler = createCatalogHandler({
+  projection,
+  path: "/__jollypixel/catalog"
+});
+```
+
+The default path is `/__jollypixel/catalog`. `GET` returns the JSON snapshot
+and `HEAD` returns the same headers without a body. Other methods on that path
+receive `405` with `Allow: GET, HEAD`. Requests for another path are passed to
+`next()`.
+
+## Vite plugin
+
+```ts
+import {
+  createAssetCatalogPlugin
+} from "@jolly-pixel/asset-server/plugins/vite.ts";
+
+export default {
+  plugins: [createAssetCatalogPlugin({ projection })]
+};
+```
+
+The plugin accepts the same optional `path` override as the HTTP handler.