@rohal12/spindle 0.52.9 → 0.54.0

package/src/saves/save-manager.ts

@@ -7,9 +7,14 @@ import type {
   SaveExport,
   StorageInfo,
 } from './types';
-import { estimatePayloadBytes, isSaveExport, isSavePayload } from './types';
+import { checkSaveExport, estimatePayloadBytes } from './types';
+import {
+  decodePayload,
+  encodePayload,
+  IncompatibleSaveError,
+  SAVE_FORMAT_VERSION,
+} from './format';
 import { getBackend, resetBackend } from './storage';
-import { serialize, deserialize } from '../class-registry';
 import { deepClone } from '../structural';
 import { emit } from '../event-emitter';
 import { withoutDraws } from '../prng';
@@ -272,30 +277,12 @@ export function saveWithHooks<T>(
 
 // --- Save CRUD ---
 
-/**
- * `payload` with `convert` applied to its live variables and to those of
- * every history moment.
- */
-function mapVariables(
-  payload: SavePayload,
-  convert: (variables: Record<string, unknown>) => Record<string, unknown>,
-): SavePayload {
-  return {
-    ...payload,
-    variables: convert(payload.variables),
-    history: payload.history.map((m) => ({
-      ...m,
-      variables: convert(m.variables),
-    })),
-  };
-}
-
-/** The record to store for a save: `payload` serialized, and its size. */
+/** The record to store for a save: `payload` encoded, and its size. */
 function storedRecord(meta: SaveMeta, payload: SavePayload): SaveRecord {
-  const serialized = mapVariables(deepClone(payload), serialize);
+  const encoded = encodePayload(payload);
   return {
-    meta: { ...meta, estimatedBytes: estimatePayloadBytes(serialized) },
-    payload: serialized,
+    meta: { ...meta, estimatedBytes: estimatePayloadBytes(encoded) },
+    payload: encoded,
   };
 }
 
@@ -372,17 +359,16 @@ async function overwriteSaveNow(
 }
 
 /**
- * Turn a stored (serialized) payload into a live one, restoring class
- * instances and built-ins. Returns a new payload; the stored one is left
- * untouched. Payloads handed to the store's `loadFromPayload()` must be live.
+ * The live payload of a stored save, if there is one (see decodePayload:
+ * throws for a save of an incompatible format). Payloads handed to the
+ * store's `loadFromPayload()` must be live.
  */
-export function deserializePayload(payload: SavePayload): SavePayload {
-  return mapVariables(payload, deserialize);
-}
-
-/** The live payload of a stored save, if there is one. */
 const livePayload = (record: SaveRecord | undefined) =>
-  record && deserializePayload(record.payload);
+  record && decodePayload(record.payload);
+
+/** The live payload of a stored record's payload (see decodePayload). */
+export const decodeSavePayload = (payload: SaveRecord['payload']) =>
+  decodePayload(payload);
 
 export const loadSave = readingSave(livePayload);
 
@@ -650,7 +636,7 @@ export function loadSlotSave(
   return inOrder(async () => {
     const record = await slotRecord(ifid, slot);
     if (!record) return undefined;
-    const payload = deserializePayload(record.payload);
+    const payload = decodePayload(record.payload);
     const { playthroughId } = record.meta;
     if (playthroughId) await adoptPlaythroughNow(ifid, playthroughId);
     return { payload, playthroughId };
@@ -715,28 +701,35 @@ export const deleteSlotSave = queued(async (ifid: string, slot?: string) => {
 const SESSION_KEY_PREFIX = 'spindle.session.';
 
 /**
- * Write a pre-serialized session payload to sessionStorage.
- * Callers are responsible for serializing variables (see persistSession in store.ts).
+ * Write the session payload to sessionStorage, encoded like a save (see
+ * encodePayload). Throws, like a save, when the state holds a value a save
+ * cannot (a function, an instance of an unregistered class, a unique
+ * symbol); the session then keeps its previous copy.
  */
-export function saveSession(ifid: string, data: unknown): void {
+export function saveSession(ifid: string, payload: SavePayload): void {
+  const text = JSON.stringify(encodePayload(payload));
   try {
-    sessionStorage.setItem(
-      `${SESSION_KEY_PREFIX}${ifid}`,
-      JSON.stringify(data),
-    );
+    sessionStorage.setItem(`${SESSION_KEY_PREFIX}${ifid}`, text);
   } catch {
     // sessionStorage unavailable or full — silently ignore
   }
 }
 
+/**
+ * The live payload of the stored session, if there is one that loads. A
+ * session written by an incompatible version of Spindle is dropped with a
+ * warning, and the story starts fresh.
+ */
 export function loadSession(ifid: string): SavePayload | undefined {
   try {
     const raw = sessionStorage.getItem(`${SESSION_KEY_PREFIX}${ifid}`);
     if (!raw) return undefined;
-    const parsed: unknown = JSON.parse(raw);
-    if (!isSavePayload(parsed)) return undefined;
-    return deserializePayload(parsed);
-  } catch {
+    return decodePayload(JSON.parse(raw));
+  } catch (err) {
+    if (err instanceof IncompatibleSaveError) {
+      console.warn(`spindle: ${err.message}; the session was not restored.`);
+      clearSession(ifid);
+    }
     return undefined;
   }
 }
@@ -755,7 +748,7 @@ export function clearSession(ifid: string): void {
 function toExport(record: SaveRecord | undefined): SaveExport | undefined {
   if (!record) return undefined;
   return {
-    version: 1,
+    formatVersion: SAVE_FORMAT_VERSION,
     ifid: record.meta.ifid,
     exportedAt: new Date().toISOString(),
     save: record,
@@ -769,23 +762,15 @@ export const exportSave = readingSave(toExport);
  * a fresh save ID, and the playthrough record created if it doesn't exist yet.
  * The returned record is not stored yet.
  */
-async function prepareImport(
-  data: SaveExport,
-  ifid: string,
-): Promise<SaveRecord> {
-  if (data.version !== 1) {
-    throw new Error(`Unsupported save version: ${data.version}`);
-  }
+async function prepareImport(data: unknown, ifid: string): Promise<SaveRecord> {
+  // Callers may pass parsed JSON; check the format version and the full
+  // structure before anything is stored or replaced
+  checkSaveExport(data);
   if (data.ifid !== ifid) {
     throw new Error(
       `Save is from a different story (expected IFID ${ifid}, got ${data.ifid})`,
     );
   }
-  // Callers may pass parsed JSON; check the full structure before anything
-  // is stored or replaced
-  if (!isSaveExport(data)) {
-    throw new Error('Invalid save file format');
-  }
 
   // Re-assign a new ID to avoid collisions
   const record = deepClone(data.save);
@@ -804,10 +789,7 @@ async function prepareImport(
   return record;
 }
 
-export function importSave(
-  data: SaveExport,
-  ifid: string,
-): Promise<SaveRecord> {
+export function importSave(data: unknown, ifid: string): Promise<SaveRecord> {
   return inOrder(async () => {
     const record = await prepareImport(data, ifid);
     await (await getBackend()).putSave(record);
@@ -828,7 +810,7 @@ export const exportSlotSave = readingSlot(toExport);
  * and slot index consistent.
  */
 export function importSlotSave(
-  data: SaveExport,
+  data: unknown,
   ifid: string,
   slot?: string,
 ): Promise<SaveInfo> {

package/src/saves/types.ts

@@ -1,5 +1,13 @@
 import type { PRNGSnapshot } from '../prng';
-import { isDeserializable } from '../class-registry';
+import { hasOwn } from '../utils/namespace';
+import {
+  checkFormatVersion,
+  decodePayload,
+  IncompatibleSaveError,
+  type EncodedPayload,
+} from './format';
+
+export type { EncodedPayload } from './format';
 
 /** History moment as persisted in saves (full variable snapshots). */
 export interface SaveHistoryMoment {
@@ -38,7 +46,8 @@ export interface SaveMeta {
 
 export interface SaveRecord {
   meta: SaveMeta;
-  payload: SavePayload;
+  /** The payload as stored, with its format version (see format.ts). */
+  payload: EncodedPayload;
 }
 
 export interface PlaythroughRecord {
@@ -59,111 +68,85 @@ export interface SaveInfo {
 }
 
 export interface SaveExport {
-  version: 1;
+  /** The save format version of the export (see SAVE_FORMAT_VERSION). */
+  formatVersion: number;
   ifid: string;
   exportedAt: string;
   save: SaveRecord;
 }
 
-export function isSaveExport(value: unknown): value is SaveExport {
-  if (typeof value !== 'object' || value === null) return false;
-  const obj = value as Record<string, unknown>;
-  if (obj.version !== 1 || typeof obj.ifid !== 'string') return false;
-  if (typeof obj.save !== 'object' || obj.save === null) return false;
-
-  const save = obj.save as Record<string, unknown>;
-  if (typeof save.meta !== 'object' || save.meta === null) return false;
-  if (typeof save.payload !== 'object' || save.payload === null) return false;
-
-  const meta = save.meta as Record<string, unknown>;
-  if (typeof meta.id !== 'string' || typeof meta.passage !== 'string')
-    return false;
-  if (typeof meta.ifid !== 'string') return false;
-  if (typeof meta.playthroughId !== 'string') return false;
-  if (typeof meta.createdAt !== 'string') return false;
-  if (typeof meta.updatedAt !== 'string') return false;
-  if (typeof meta.title !== 'string') return false;
-
-  return isImportablePayload(save.payload);
-}
+const INVALID_FILE = 'Invalid save file format';
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** Absent, null, or a `{ seed, pull }` PRNG snapshot. */
-function isOptionalPRNGSnapshot(value: unknown): boolean {
-  if (value == null) return true;
-  return (
-    isRecord(value) &&
-    typeof value.seed === 'string' &&
-    typeof value.pull === 'number' &&
-    Number.isInteger(value.pull) &&
-    value.pull >= 0
-  );
-}
-
-/** A variable container whose values deserialize() can restore. */
-function isSerializedVariables(value: unknown): boolean {
-  return isRecord(value) && isDeserializable(value);
-}
-
-function isSaveHistoryMoment(value: unknown): value is SaveHistoryMoment {
-  return (
-    isRecord(value) &&
-    typeof value.passage === 'string' &&
-    isSerializedVariables(value.variables) &&
-    typeof value.timestamp === 'number' &&
-    isOptionalPRNGSnapshot(value.prng)
-  );
+const META_STRINGS = [
+  'id',
+  'passage',
+  'ifid',
+  'playthroughId',
+  'createdAt',
+  'updatedAt',
+  'title',
+] as const;
+
+/** decodePayload(), without the warnings for unregistered classes. */
+function decodeQuietly(encoded: unknown): void {
+  const warn = console.warn;
+  console.warn = () => {};
+  try {
+    decodePayload(encoded);
+  } finally {
+    console.warn = warn;
+  }
 }
 
 /**
- * Full check of a payload from outside the running story (an imported save):
- * every history moment is well formed, `historyIndex` is an integer that
- * points at a moment of the payload's passage, and the encoded values (Map,
- * Set, Date, RegExp, class instances) in the live variables and every
- * moment's variables have the shape deserialize() expects. Anything that
- * passes can be stored and later loaded.
+ * Check data from outside the running story (an imported save) in full:
+ * the export's and the payload's format versions, the record's metadata,
+ * and that the payload decodes (see decodePayload). Throws an
+ * IncompatibleSaveError for a missing or unknown format version, and an
+ * "Invalid save file format" error for anything else that is wrong.
+ * Anything that passes can be stored and later loaded.
  */
-function isImportablePayload(value: unknown): value is SavePayload {
-  if (!isRecord(value)) return false;
-  if (typeof value.passage !== 'string') return false;
-  if (!isSerializedVariables(value.variables)) return false;
-
-  const { history, historyIndex } = value;
-  if (!Array.isArray(history) || history.length === 0) return false;
-  // Array.from: every() skips the holes of a sparse array
-  if (!Array.from(history).every(isSaveHistoryMoment)) return false;
-  if (
-    typeof historyIndex !== 'number' ||
-    !Number.isInteger(historyIndex) ||
-    historyIndex < 0 ||
-    historyIndex >= history.length
-  ) {
-    return false;
+export function checkSaveExport(value: unknown): asserts value is SaveExport {
+  if (!isRecord(value)) throw new Error(INVALID_FILE);
+  // An export from before format versions has `version: 1`: incompatible.
+  // Data that is no export at all is invalid.
+  if (!hasOwn(value, 'formatVersion')) {
+    throw value.version === 1
+      ? new IncompatibleSaveError()
+      : new Error(INVALID_FILE);
+  }
+  checkFormatVersion(value.formatVersion);
+  if (typeof value.ifid !== 'string') throw new Error(INVALID_FILE);
+  const save = value.save;
+  if (!isRecord(save) || !isRecord(save.meta)) throw new Error(INVALID_FILE);
+  const meta = save.meta;
+  if (META_STRINGS.some((key) => typeof meta[key] !== 'string')) {
+    throw new Error(INVALID_FILE);
+  }
+  try {
+    decodeQuietly(save.payload);
+  } catch (err) {
+    if (err instanceof IncompatibleSaveError) throw err;
+    throw new Error(INVALID_FILE);
   }
-  if (history[historyIndex]!.passage !== value.passage) return false;
-
-  if (value.visitCounts !== undefined && !isRecord(value.visitCounts))
-    return false;
-  if (value.renderCounts !== undefined && !isRecord(value.renderCounts))
-    return false;
-  return isOptionalPRNGSnapshot(value.prng);
 }
 
-export function isSavePayload(value: unknown): value is SavePayload {
-  if (typeof value !== 'object' || value === null) return false;
-  const obj = value as Record<string, unknown>;
-  if (typeof obj.passage !== 'string') return false;
-  if (typeof obj.variables !== 'object' || obj.variables === null) return false;
-  if (!Array.isArray(obj.history) || obj.history.length === 0) return false;
-  if (typeof obj.historyIndex !== 'number') return false;
-  return true;
+/** Whether checkSaveExport() accepts `value`. */
+export function isSaveExport(value: unknown): value is SaveExport {
+  try {
+    checkSaveExport(value);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-/** Estimated byte size of a serialized save payload. */
-export function estimatePayloadBytes(payload: SavePayload): number {
+/** Estimated byte size of a stored payload. */
+export function estimatePayloadBytes(payload: EncodedPayload): number {
   return JSON.stringify(payload).length;
 }