@yagejs/save 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # @yagejs/save
 
-Save and load game state for the [YAGE](https://yage.dev) 2D game engine.
+Persistence for the [YAGE](https://yage.dev) 2D game engine — typed reactive
+stores plus a snapshot path for full-scene quicksave.
 
 ## Install
 
@@ -8,40 +9,92 @@ Save and load game state for the [YAGE](https://yage.dev) 2D game engine.
 npm install @yagejs/save
 ```
 
-## Usage
+## Stores + Save instance (primary path)
+
+Most save data is *intentional* — settings, save slots, world facts,
+progression. Define typed stores at module scope, construct one `Save`
+instance, register it via the plugin.
 
 ```ts
 import { Engine } from "@yagejs/core";
-import { SavePlugin, SaveServiceKey } from "@yagejs/save";
+import {
+  defineStore, defineSet,
+  createSave, SavePlugin, localStorageAdapter,
+} from "@yagejs/save";
+
+interface Settings { music: number; sfx: number }
+interface RunData { chapter: number; position: { x: number; y: number } }
+
+const settings = defineStore<Settings>("settings", {
+  defaults: () => ({ music: 0.8, sfx: 1.0 }),
+});
+const opened = defineSet<string>("world.opened");
+const saves = defineStore<RunData>("saves", {
+  defaults: () => ({ chapter: 1, position: { x: 0, y: 0 } }),
+});
+
+const save = createSave({ adapter: localStorageAdapter() });
+
+await save.restoreAll([settings, opened, saves]);
+save.autoPersist(settings);
 
 const engine = new Engine();
-engine.use(new SavePlugin());
+engine.use(new SavePlugin({ save }));
 ```
 
-Mark components as serializable and save the world:
+In-game components resolve the registered Save through `SaveServiceKey`:
 
 ```ts
-import { serializable } from "@yagejs/core";
-
-@serializable("player-stats")
-class PlayerStats extends Component {
-  constructor(public hp = 100, public xp = 0) { super(); }
+import { SaveServiceKey } from "@yagejs/save";
+
+class CheckpointOnRest extends Component {
+  setup() {
+    this.entity.on(Rested, async () => {
+      const save = this.use(SaveServiceKey);
+      await save.saveSlot(saves, "auto");
+    });
+  }
 }
+```
+
+Save slots with typed metadata:
+
+```ts
+interface RunMeta { location: string; playtime: number }
+await save.saveSlot<RunMeta>(saves, "manual-1", { metadata: { /* … */ } });
+const slots = await save.listSlots<RunMeta>(saves);
+await save.loadSlot(saves, "manual-1");
+```
+
+## Snapshot path (advanced)
+
+Full-scene serialization via `@serializable` decorators. Use for quicksave
+that captures every entity, component, and active process.
+
+```ts
+import { serializable } from "@yagejs/core";
+import { SnapshotPlugin, SnapshotServiceKey } from "@yagejs/save";
 
-// Save
-const saveService = engine.context.resolve(SaveServiceKey);
-await saveService.save("slot-1");
+@serializable
+class Player extends Entity { /* ... */ }
 
-// Load
-await saveService.load("slot-1");
+engine.use(new SnapshotPlugin());
+const snap = engine.context.resolve(SnapshotServiceKey);
+snap.saveSnapshot("slot-1");
+await snap.loadSnapshot("slot-1");
 ```
 
 ## What's in the box
 
-- **SavePlugin / SaveService** - snapshot the entire engine state
-- **Pluggable storage** - `LocalStorageSaveStorage` included; implement `SaveStorage` for custom backends (IndexedDB, files, remote, etc.)
-- **@serializable decorator** - opt components into save/load
-- **Typed slots** - multiple save slots with metadata
+- **Stores** — `defineStore`, `defineSet`, `defineMap`, `defineCounter`
+  (re-exported from `@yagejs/core`).
+- **Save** — `createSave({ adapter })` with `persist`, `restore`, `saveSlot`,
+  `loadSlot`, `listSlots`, `deleteSlot`, `autoPersist`.
+- **Adapters** — `localStorageAdapter`, `memoryAdapter`. Implement
+  `SaveAdapter` for IndexedDB, files, cloud, etc.
+- **Codecs** — `jsonCodec`, `setCodec`, `mapCodec`, `dateCodec`.
+- **Snapshot system** — `SnapshotPlugin`, `SnapshotService`, `@serializable`
+  decorator (in `@yagejs/core`), snapshot contributors.
 
 ## Docs
 

package/dist/index.cjs

@@ -21,19 +21,375 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  LocalStorageSaveStorage: () => LocalStorageSaveStorage,
+  InvalidKeyError: () => InvalidKeyError,
+  LocalStorageSnapshotStorage: () => LocalStorageSnapshotStorage,
+  Save: () => Save,
   SavePlugin: () => SavePlugin,
-  SaveService: () => SaveService,
   SaveServiceKey: () => SaveServiceKey,
-  VERSION: () => import_core3.VERSION
+  SlotNotFoundError: () => SlotNotFoundError,
+  SnapshotPlugin: () => SnapshotPlugin,
+  SnapshotService: () => SnapshotService,
+  SnapshotServiceKey: () => SnapshotServiceKey,
+  StoreMigrationMissingError: () => import_core5.StoreMigrationMissingError,
+  StoreVersionTooNewError: () => import_core5.StoreVersionTooNewError,
+  VERSION: () => import_core4.VERSION,
+  createSave: () => createSave,
+  dateCodec: () => import_core5.dateCodec,
+  defineCounter: () => import_core5.defineCounter,
+  defineMap: () => import_core5.defineMap,
+  defineSet: () => import_core5.defineSet,
+  defineStore: () => import_core5.defineStore,
+  jsonCodec: () => import_core5.jsonCodec,
+  localStorageAdapter: () => localStorageAdapter,
+  mapCodec: () => import_core5.mapCodec,
+  memoryAdapter: () => memoryAdapter,
+  setCodec: () => import_core5.setCodec
 });
 module.exports = __toCommonJS(index_exports);
-var import_core3 = require("@yagejs/core");
+var import_core4 = require("@yagejs/core");
+var import_core5 = require("@yagejs/core");
+
+// src/Save.ts
+var SlotNotFoundError = class extends Error {
+  static {
+    __name(this, "SlotNotFoundError");
+  }
+  storeId;
+  slot;
+  constructor(storeId, slot) {
+    super(`No save found for store "${storeId}" in slot "${slot}".`);
+    this.name = "SlotNotFoundError";
+    this.storeId = storeId;
+    this.slot = slot;
+  }
+};
+var InvalidKeyError = class extends Error {
+  static {
+    __name(this, "InvalidKeyError");
+  }
+  constructor(message) {
+    super(message);
+    this.name = "InvalidKeyError";
+  }
+};
+var SEP = "/";
+var DOC_TAG = "d";
+var SLOT_TAG = "s";
+var MANIFEST_TAG = "m";
+function validateStoreId(id) {
+  if (id.length === 0) {
+    throw new InvalidKeyError("Save: store id must be non-empty.");
+  }
+}
+__name(validateStoreId, "validateStoreId");
+function validateSlotName(slot) {
+  if (slot.length === 0) {
+    throw new InvalidKeyError("Save: slot name must be non-empty.");
+  }
+}
+__name(validateSlotName, "validateSlotName");
+function docKey(id) {
+  validateStoreId(id);
+  return `${encodeURIComponent(id)}${SEP}${DOC_TAG}`;
+}
+__name(docKey, "docKey");
+function slotKey(id, slot) {
+  validateStoreId(id);
+  validateSlotName(slot);
+  return `${encodeURIComponent(id)}${SEP}${SLOT_TAG}${SEP}${encodeURIComponent(slot)}`;
+}
+__name(slotKey, "slotKey");
+function manifestKey(id) {
+  validateStoreId(id);
+  return `${encodeURIComponent(id)}${SEP}${MANIFEST_TAG}`;
+}
+__name(manifestKey, "manifestKey");
+async function readManifest(adapter, id) {
+  const raw = await adapter.read(manifestKey(id));
+  if (raw == null) return { version: 1, slots: {} };
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && parsed.slots) {
+      return { version: 1, slots: parsed.slots };
+    }
+  } catch {
+  }
+  return { version: 1, slots: {} };
+}
+__name(readManifest, "readManifest");
+async function writeManifest(adapter, id, manifest) {
+  await adapter.write(manifestKey(id), JSON.stringify(manifest));
+}
+__name(writeManifest, "writeManifest");
+var Save = class {
+  static {
+    __name(this, "Save");
+  }
+  adapter;
+  /**
+   * Per-store manifest update queue. Two concurrent saveSlot/deleteSlot calls
+   * against the same store would otherwise read-modify-write the manifest
+   * blindly — the later writer wins and the earlier change is silently lost.
+   * Funnelling manifest mutations through a per-store promise chain serializes
+   * them while leaving slot data writes (which target distinct keys)
+   * unaffected. Per-store, not global, because manifests for different stores
+   * never collide.
+   */
+  manifestQueues = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.adapter = opts.adapter;
+  }
+  /** Persist the store as an unslotted document. */
+  async persist(store) {
+    const payload = store.serialize();
+    await this.adapter.write(docKey(store.id), JSON.stringify(payload));
+  }
+  /**
+   * Restore an unslotted document into the store. No-op when the document
+   * doesn't exist — the store keeps its current (default) value.
+   */
+  async restore(store) {
+    const raw = await this.adapter.read(docKey(store.id));
+    if (raw == null) return;
+    store.hydrate(JSON.parse(raw));
+  }
+  /** Restore many stores in parallel. */
+  async restoreAll(stores) {
+    await Promise.all(stores.map((s) => this.restore(s)));
+  }
+  /**
+   * Save the store into a named slot. The slot manifest is updated with the
+   * timestamp and optional metadata.
+   */
+  async saveSlot(store, slot, opts) {
+    const payload = store.serialize();
+    await this.adapter.write(slotKey(store.id, slot), JSON.stringify(payload));
+    const entry = {
+      name: slot,
+      savedAt: Date.now()
+    };
+    if (opts?.metadata !== void 0) entry.metadata = opts.metadata;
+    await this.updateManifest(store.id, (manifest) => {
+      manifest.slots[slot] = entry;
+    });
+  }
+  /** Load a slot into the store. Throws `SlotNotFoundError` when missing. */
+  async loadSlot(store, slot) {
+    const raw = await this.adapter.read(slotKey(store.id, slot));
+    if (raw == null) throw new SlotNotFoundError(store.id, slot);
+    store.hydrate(JSON.parse(raw));
+  }
+  /** List slots for a store, optionally filtered by prefix. */
+  async listSlots(store, opts) {
+    const manifest = await readManifest(this.adapter, store.id);
+    const entries = Object.values(manifest.slots);
+    const filtered = opts?.prefix !== void 0 ? entries.filter((e) => e.name.startsWith(opts.prefix)) : entries;
+    return filtered.map((e) => {
+      const info = { name: e.name, savedAt: e.savedAt };
+      if (e.metadata !== void 0) info.metadata = e.metadata;
+      return info;
+    });
+  }
+  /** Delete a slot. No-op when the slot doesn't exist. */
+  async deleteSlot(store, slot) {
+    await this.adapter.delete(slotKey(store.id, slot));
+    await this.updateManifest(store.id, (manifest) => {
+      if (!(slot in manifest.slots)) return;
+      const next = {};
+      for (const [name, entry] of Object.entries(manifest.slots)) {
+        if (name !== slot) next[name] = entry;
+      }
+      manifest.slots = next;
+    });
+  }
+  /**
+   * Read-modify-write the manifest for a store, serialized through the
+   * per-store queue. The mutator runs on the freshly-read manifest; if it's
+   * a no-op the write is skipped (the mutator can opt out by leaving the
+   * passed manifest unchanged — but we always write back to keep the contract
+   * predictable; a no-op write is cheap).
+   */
+  updateManifest(storeId, mutate) {
+    const prev = this.manifestQueues.get(storeId) ?? Promise.resolve();
+    const next = prev.then(async () => {
+      const manifest = await readManifest(this.adapter, storeId);
+      mutate(manifest);
+      await writeManifest(this.adapter, storeId, manifest);
+    });
+    this.manifestQueues.set(
+      storeId,
+      next.catch(() => void 0)
+    );
+    return next;
+  }
+  /**
+   * Subscribe to the store and persist on every change, coalesced to a single
+   * in-flight write per store. Returns a stop function — call it to
+   * unsubscribe.
+   *
+   * Writes are serialized: while a `persist()` is in flight, further changes
+   * mark the store dirty and trigger one more write *after* the current one
+   * resolves. The last-set state always wins, even on a slow async adapter,
+   * because each flush re-reads `store.serialize()` rather than capturing the
+   * value at scheduling time. Multiple synchronous `set` calls collapse into
+   * one write because the dirty flag is consumed atomically.
+   *
+   * `setTimeout` is intentionally not used here: `Save` runs alongside the
+   * page lifecycle, not the engine loop, and may be active before the engine
+   * starts or after it stops (e.g. settings menus on a paused game). Using
+   * engine-time processes here would tie persistence to a running scheduler.
+   */
+  autoPersist(store) {
+    let inFlight = false;
+    let dirty = false;
+    let stopped = false;
+    const flush = /* @__PURE__ */ __name(async () => {
+      while (dirty && !stopped) {
+        dirty = false;
+        try {
+          await this.persist(store);
+        } catch (err) {
+          console.error(
+            `autoPersist: failed to persist store "${store.id}":`,
+            err
+          );
+        }
+      }
+      inFlight = false;
+    }, "flush");
+    const off = store.subscribe(() => {
+      if (stopped) return;
+      dirty = true;
+      if (inFlight) return;
+      inFlight = true;
+      queueMicrotask(() => {
+        if (stopped) {
+          inFlight = false;
+          return;
+        }
+        void flush();
+      });
+    });
+    return () => {
+      stopped = true;
+      off();
+    };
+  }
+};
+function createSave(opts) {
+  return new Save(opts);
+}
+__name(createSave, "createSave");
+
+// src/keys.ts
+var import_core = require("@yagejs/core");
+var SaveServiceKey = new import_core.ServiceKey("save");
+
+// src/SavePlugin.ts
+var SavePlugin = class {
+  static {
+    __name(this, "SavePlugin");
+  }
+  name = "save";
+  version = "1.0.0";
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  install(context) {
+    context.register(SaveServiceKey, this.options.save);
+  }
+};
+
+// src/adapters/memory.ts
+function memoryAdapter() {
+  const data = /* @__PURE__ */ new Map();
+  return {
+    async read(key) {
+      return data.get(key) ?? null;
+    },
+    async write(key, value) {
+      data.set(key, value);
+    },
+    async delete(key) {
+      data.delete(key);
+    },
+    async list(prefix) {
+      const out = [];
+      for (const k of data.keys()) {
+        if (k.startsWith(prefix)) out.push(k);
+      }
+      return out;
+    }
+  };
+}
+__name(memoryAdapter, "memoryAdapter");
+
+// src/adapters/localStorage.ts
+function localStorageAdapter(opts = {}) {
+  const namespace = opts.namespace ?? "yage";
+  const prefix = `${namespace}:`;
+  const ls = /* @__PURE__ */ __name(() => {
+    if (typeof window === "undefined") {
+      throw new Error(
+        "localStorageAdapter: window is not available in this environment."
+      );
+    }
+    try {
+      const storage = window.localStorage;
+      if (!storage) {
+        throw new Error(
+          "localStorageAdapter: window.localStorage is not available in this environment."
+        );
+      }
+      return storage;
+    } catch (err) {
+      throw new Error(
+        "localStorageAdapter: window.localStorage is not available in this environment.",
+        { cause: err }
+      );
+    }
+  }, "ls");
+  return {
+    async read(key) {
+      return ls().getItem(prefix + key);
+    },
+    async write(key, value) {
+      try {
+        ls().setItem(prefix + key, value);
+      } catch (err) {
+        if (err instanceof DOMException && (err.name === "QuotaExceededError" || err.name === "NS_ERROR_DOM_QUOTA_REACHED")) {
+          throw new Error(
+            `localStorageAdapter: quota exceeded while writing "${prefix + key}". Consider deleting old slots or using a different adapter.`,
+            { cause: err }
+          );
+        }
+        throw err;
+      }
+    },
+    async delete(key) {
+      ls().removeItem(prefix + key);
+    },
+    async list(keyPrefix) {
+      const storage = ls();
+      const full = prefix + keyPrefix;
+      const out = [];
+      for (let i = 0; i < storage.length; i += 1) {
+        const k = storage.key(i);
+        if (k != null && k.startsWith(full)) {
+          out.push(k.slice(prefix.length));
+        }
+      }
+      return out;
+    }
+  };
+}
+__name(localStorageAdapter, "localStorageAdapter");
 
-// src/LocalStorageAdapter.ts
-var LocalStorageSaveStorage = class {
+// src/snapshot/LocalStorageSnapshotStorage.ts
+var LocalStorageSnapshotStorage = class {
   static {
-    __name(this, "LocalStorageSaveStorage");
+    __name(this, "LocalStorageSnapshotStorage");
   }
   load(key) {
     return localStorage.getItem(key);
@@ -56,8 +412,8 @@ var LocalStorageSaveStorage = class {
   }
 };
 
-// src/SaveService.ts
-var import_core = require("@yagejs/core");
+// src/snapshot/SnapshotService.ts
+var import_core2 = require("@yagejs/core");
 var SNAPSHOT_VERSION = 4;
 var COMPONENT_ORDER = [
   "Transform",
@@ -71,9 +427,9 @@ var COMPONENT_ORDER = [
   "ParticleEmitterComponent",
   "TilemapComponent"
 ];
-var SaveService = class {
+var SnapshotService = class {
   static {
-    __name(this, "SaveService");
+    __name(this, "SnapshotService");
   }
   storage;
   context;
@@ -192,15 +548,15 @@ var SaveService = class {
     }
   }
   buildSnapshot() {
-    const sceneManager = this.context.resolve(import_core.SceneManagerKey);
+    const sceneManager = this.context.resolve(import_core2.SceneManagerKey);
     const scenes = [];
     for (const scene of sceneManager.all) {
-      if (!(0, import_core.isSerializable)(scene)) continue;
-      const type = (0, import_core.getSerializableType)(scene);
+      if (!(0, import_core2.isSerializable)(scene)) continue;
+      const type = (0, import_core2.getSerializableType)(scene);
       if (!type) continue;
       const entities = [];
       for (const entity of scene.getEntities()) {
-        if (!(0, import_core.isSerializable)(entity)) continue;
+        if (!(0, import_core2.isSerializable)(entity)) continue;
         entities.push(this.serializeEntity(entity));
       }
       const userData = scene.serialize?.();
@@ -222,7 +578,7 @@ var SaveService = class {
         }
       } catch (err) {
         console.error(
-          `SaveService: contributor "${key}" serialize failed; omitting its extras from this snapshot.`,
+          `SnapshotService: contributor "${key}" serialize failed; omitting its extras from this snapshot.`,
           err
         );
       }
@@ -245,10 +601,10 @@ var SaveService = class {
           `Save version mismatch: expected ${SNAPSHOT_VERSION}, got ${snapshot.version}.`
         );
       }
-      const sceneManager = this.context.resolve(import_core.SceneManagerKey);
+      const sceneManager = this.context.resolve(import_core2.SceneManagerKey);
       await sceneManager.popAll();
       for (const entry of snapshot.scenes) {
-        const SceneClass = import_core.SerializableRegistry.get(entry.type);
+        const SceneClass = import_core2.SerializableRegistry.get(entry.type);
         if (!SceneClass) {
           throw new Error(
             `Cannot load scene type "${entry.type}". Ensure the scene class is decorated with @serializable.`
@@ -269,7 +625,7 @@ var SaveService = class {
           await contributor.restore(extras[key]);
         } catch (err) {
           console.error(
-            `SaveService: contributor "${key}" restore failed; continuing.`,
+            `SnapshotService: contributor "${key}" restore failed; continuing.`,
             err
           );
         }
@@ -277,7 +633,7 @@ var SaveService = class {
       for (const key of Object.keys(extras)) {
         if (!this.contributors.has(key)) {
           console.warn(
-            `SaveService: snapshot contains extras for "${key}" but no contributor is registered \u2014 skipping.`
+            `SnapshotService: snapshot contains extras for "${key}" but no contributor is registered \u2014 skipping.`
           );
         }
       }
@@ -289,7 +645,7 @@ var SaveService = class {
     const idMap = /* @__PURE__ */ new Map();
     const entityEntries = [];
     for (const entityEntry of entry.entities) {
-      const EntityClass = import_core.SerializableRegistry.get(entityEntry.type);
+      const EntityClass = import_core2.SerializableRegistry.get(entityEntry.type);
       if (!EntityClass) {
         console.warn(
           `Entity type "${entityEntry.type}" not found in registry \u2014 skipping.`
@@ -331,14 +687,14 @@ var SaveService = class {
     scene.afterRestore?.(entry.userData, resolver);
   }
   serializeEntity(entity) {
-    const type = (0, import_core.getSerializableType)(entity);
+    const type = (0, import_core2.getSerializableType)(entity);
     if (!type) throw new Error("Entity is not serializable");
     const components = [];
     for (const component of entity.getAll()) {
       if (typeof component.serialize !== "function") continue;
       const data = component.serialize();
       if (data == null) continue;
-      const compType = (0, import_core.getSerializableType)(component) ?? component.constructor.name;
+      const compType = (0, import_core2.getSerializableType)(component) ?? component.constructor.name;
       components.push({ type: compType, data });
     }
     const userData = entity.serialize?.();
@@ -348,7 +704,7 @@ var SaveService = class {
       components,
       userData
     };
-    if (entity.parent && (0, import_core.isSerializable)(entity.parent)) {
+    if (entity.parent && (0, import_core2.isSerializable)(entity.parent)) {
       result.parentId = entity.parent.id;
       for (const [name, child] of entity.parent.children) {
         if (child === entity) {
@@ -371,7 +727,7 @@ var SaveService = class {
     });
     const restored = [];
     for (const snap of sorted) {
-      const CompClass = import_core.SerializableRegistry.get(snap.type);
+      const CompClass = import_core2.SerializableRegistry.get(snap.type);
       if (!CompClass || typeof CompClass.fromSnapshot !== "function") {
         continue;
       }
@@ -383,33 +739,53 @@ var SaveService = class {
   }
 };
 
-// src/keys.ts
-var import_core2 = require("@yagejs/core");
-var SaveServiceKey = new import_core2.ServiceKey("saveService");
+// src/snapshot/keys.ts
+var import_core3 = require("@yagejs/core");
+var SnapshotServiceKey = new import_core3.ServiceKey(
+  "snapshotService"
+);
 
-// src/SavePlugin.ts
-var SavePlugin = class {
+// src/snapshot/SnapshotPlugin.ts
+var SnapshotPlugin = class {
   static {
-    __name(this, "SavePlugin");
+    __name(this, "SnapshotPlugin");
   }
-  name = "save";
+  name = "snapshot";
   version = "1.0.0";
   options;
   constructor(options) {
     this.options = options ?? {};
   }
   install(context) {
-    const storage = this.options.storage ?? new LocalStorageSaveStorage();
-    const service = new SaveService(storage, context, this.options.namespace);
-    context.register(SaveServiceKey, service);
+    const storage = this.options.storage ?? new LocalStorageSnapshotStorage();
+    const service = new SnapshotService(storage, context, this.options.namespace);
+    context.register(SnapshotServiceKey, service);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  LocalStorageSaveStorage,
+  InvalidKeyError,
+  LocalStorageSnapshotStorage,
+  Save,
   SavePlugin,
-  SaveService,
   SaveServiceKey,
-  VERSION
+  SlotNotFoundError,
+  SnapshotPlugin,
+  SnapshotService,
+  SnapshotServiceKey,
+  StoreMigrationMissingError,
+  StoreVersionTooNewError,
+  VERSION,
+  createSave,
+  dateCodec,
+  defineCounter,
+  defineMap,
+  defineSet,
+  defineStore,
+  jsonCodec,
+  localStorageAdapter,
+  mapCodec,
+  memoryAdapter,
+  setCodec
 });
 //# sourceMappingURL=index.cjs.map