@rohal12/spindle 0.50.1 → 0.51.0

package/dist/pkg/headless.js

@@ -3489,6 +3489,16 @@ function restorePRNGFromMoment(moment) {
 	if (moment?.prng) restorePRNG(moment.prng.seed, moment.prng.pull);
 	else if (moment) resetPRNG();
 }
+/**
+* Return `p` marked as handled: a caller that ignores the result of a
+* fire-and-forget operation (whose failure is already logged) gets no
+* unhandled-rejection report, while a caller that awaits it still sees the
+* error.
+*/
+function handled(p) {
+	p.catch(() => {});
+	return p;
+}
 var useStoryStore = create()(immer((set, get) => ({
 	storyData: null,
 	currentPassage: "",
@@ -3754,8 +3764,8 @@ var useStoryStore = create()(immer((set, get) => ({
 	},
 	save: (slot, custom) => {
 		const { storyData, playthroughId } = get();
-		if (!storyData) return;
-		saveWithHooks(slot, custom, () => get().getSavePayload(), async (payload) => {
+		if (!storyData) return Promise.resolve();
+		return handled(saveWithHooks(slot, custom, () => get().getSavePayload(), async (payload) => {
 			set((state) => {
 				state.saveError = null;
 			});
@@ -3771,15 +3781,16 @@ var useStoryStore = create()(immer((set, get) => ({
 			set((state) => {
 				state.saveError = err instanceof Error ? err.message : "Failed to save";
 			});
-		});
+			throw err;
+		}));
 	},
 	load: (slot) => {
 		const { storyData } = get();
-		if (!storyData) return;
+		if (!storyData) return Promise.resolve();
 		set((state) => {
 			state.loadError = null;
 		});
-		loadQuickSave(storyData.ifid, slot).then((payload) => {
+		return handled(loadQuickSave(storyData.ifid, slot).then((payload) => {
 			if (!payload) return;
 			get().loadFromPayload(payload, slot);
 		}).catch((err) => {
@@ -3787,7 +3798,8 @@ var useStoryStore = create()(immer((set, get) => ({
 			set((state) => {
 				state.loadError = err instanceof Error ? err.message : "Failed to load";
 			});
-		});
+			throw err;
+		}));
 	},
 	hasSave: (slot) => {
 		const { storyData, knownSaves } = get();
@@ -3806,8 +3818,8 @@ var useStoryStore = create()(immer((set, get) => ({
 	},
 	deleteSave: (slot) => {
 		const { storyData } = get();
-		if (!storyData) return;
-		deleteSlotSave(storyData.ifid, slot).then(() => {
+		if (!storyData) return Promise.resolve();
+		return handled(deleteSlotSave(storyData.ifid, slot).then(() => {
 			set((state) => {
 				const key = slot ?? "";
 				const { [key]: _, ...rest } = state.knownSaves;
@@ -3815,7 +3827,8 @@ var useStoryStore = create()(immer((set, get) => ({
 			});
 		}).catch((err) => {
 			console.error("spindle: failed to delete save", err);
-		});
+			throw err;
+		}));
 	},
 	exportSave: async (slot) => {
 		const { storyData } = get();
@@ -4739,10 +4752,10 @@ function createStoryAPI() {
 			useStoryStore.getState().restart();
 		},
 		save(slot, custom) {
-			useStoryStore.getState().save(slot, custom);
+			return useStoryStore.getState().save(slot, custom);
 		},
 		load(slot) {
-			useStoryStore.getState().load(slot);
+			return useStoryStore.getState().load(slot);
 		},
 		hasSave(slot) {
 			return useStoryStore.getState().hasSave(slot);
@@ -4754,7 +4767,7 @@ function createStoryAPI() {
 			return useStoryStore.getState().listSaves();
 		},
 		deleteSave(slot) {
-			useStoryStore.getState().deleteSave(slot);
+			return useStoryStore.getState().deleteSave(slot);
 		},
 		exportSave(slot) {
 			return useStoryStore.getState().exportSave(slot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.50.1",
+  "version": "0.51.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/store.ts

@@ -370,12 +370,12 @@ export interface StoryState {
   updateVariables: (recipe: (draft: VariableNamespaces) => void) => void;
   trackRender: (passageName: string) => void;
   restart: () => void;
-  save: (slot?: string, custom?: Record<string, unknown>) => void;
-  load: (slot?: string) => void;
+  save: (slot?: string, custom?: Record<string, unknown>) => Promise<void>;
+  load: (slot?: string) => Promise<void>;
   hasSave: (slot?: string) => boolean;
   getSaveInfo: (slot?: string) => Promise<SaveInfo | null>;
   listSaves: () => Promise<SaveInfo[]>;
-  deleteSave: (slot?: string) => void;
+  deleteSave: (slot?: string) => Promise<void>;
   exportSave: (slot?: string) => Promise<SaveExport | null>;
   importSave: (data: unknown, slot?: string) => Promise<SaveInfo>;
   clearGameData: () => void;
@@ -395,6 +395,17 @@ export interface StoryState {
   clearDeferredRender: () => void;
 }
 
+/**
+ * Return `p` marked as handled: a caller that ignores the result of a
+ * fire-and-forget operation (whose failure is already logged) gets no
+ * unhandled-rejection report, while a caller that awaits it still sees the
+ * error.
+ */
+function handled<T>(p: Promise<T>): Promise<T> {
+  p.catch(() => {});
+  return p;
+}
+
 export const useStoryStore = create<StoryState>()(
   immer((set, get) => ({
     storyData: null,
@@ -781,52 +792,64 @@ export const useStoryStore = create<StoryState>()(
 
     save: (slot?: string, custom?: Record<string, unknown>) => {
       const { storyData, playthroughId } = get();
-      if (!storyData) return;
-
-      saveWithHooks(
-        slot,
-        custom,
-        () => get().getSavePayload(),
-        async (payload) => {
-          set((state) => {
-            state.saveError = null;
-          });
-          await quickSave(storyData.ifid, playthroughId, payload, slot, custom);
+      if (!storyData) return Promise.resolve();
+
+      return handled(
+        saveWithHooks(
+          slot,
+          custom,
+          () => get().getSavePayload(),
+          async (payload) => {
+            set((state) => {
+              state.saveError = null;
+            });
+            await quickSave(
+              storyData.ifid,
+              playthroughId,
+              payload,
+              slot,
+              custom,
+            );
+            set((state) => {
+              state.knownSaves = {
+                ...state.knownSaves,
+                [slot ?? '']: true,
+              };
+            });
+          },
+        ).catch((err) => {
+          console.error('spindle: failed to save', err);
           set((state) => {
-            state.knownSaves = {
-              ...state.knownSaves,
-              [slot ?? '']: true,
-            };
+            state.saveError =
+              err instanceof Error ? err.message : 'Failed to save';
           });
-        },
-      ).catch((err) => {
-        console.error('spindle: failed to save', err);
-        set((state) => {
-          state.saveError =
-            err instanceof Error ? err.message : 'Failed to save';
-        });
-      });
+          throw err;
+        }),
+      );
     },
 
     load: (slot?: string) => {
       const { storyData } = get();
-      if (!storyData) return;
+      if (!storyData) return Promise.resolve();
 
       set((state) => {
         state.loadError = null;
       });
-      loadQuickSave(storyData.ifid, slot)
-        .then((payload) => {
-          if (!payload) return;
-          get().loadFromPayload(payload, slot);
-        })
-        .catch((err) => {
-          console.error('spindle: failed to load save', err);
-          set((state) => {
-            state.loadError =
-              err instanceof Error ? err.message : 'Failed to load';
-          });
-        });
+      return handled(
+        loadQuickSave(storyData.ifid, slot)
+          .then((payload) => {
+            if (!payload) return;
+            get().loadFromPayload(payload, slot);
+          })
+          .catch((err) => {
+            console.error('spindle: failed to load save', err);
+            set((state) => {
+              state.loadError =
+                err instanceof Error ? err.message : 'Failed to load';
+            });
+            throw err;
+          }),
+      );
     },
 
     hasSave: (slot?: string) => {
@@ -849,19 +872,22 @@ export const useStoryStore = create<StoryState>()(
 
     deleteSave: (slot?: string) => {
       const { storyData } = get();
-      if (!storyData) return;
+      if (!storyData) return Promise.resolve();
 
-      deleteSlotSave(storyData.ifid, slot)
-        .then(() => {
-          set((state) => {
-            const key = slot ?? '';
-            const { [key]: _, ...rest } = state.knownSaves;
-            state.knownSaves = rest as Record<string, true>;
-          });
-        })
-        .catch((err) => {
-          console.error('spindle: failed to delete save', err);
-        });
+      return handled(
+        deleteSlotSave(storyData.ifid, slot)
+          .then(() => {
+            set((state) => {
+              const key = slot ?? '';
+              const { [key]: _, ...rest } = state.knownSaves;
+              state.knownSaves = rest as Record<string, true>;
+            });
+          })
+          .catch((err) => {
+            console.error('spindle: failed to delete save', err);
+            throw err;
+          }),
+      );
     },
 
     exportSave: async (slot?: string): Promise<SaveExport | null> => {

package/src/story-api.ts

@@ -155,12 +155,12 @@ export interface StoryAPI {
   back(): void;
   forward(): void;
   restart(): void;
-  save(slot?: string, custom?: Record<string, unknown>): void;
-  load(slot?: string): void;
+  save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
+  load(slot?: string): Promise<void>;
   hasSave(slot?: string): boolean;
   getSaveInfo(slot?: string): Promise<SaveInfo | null>;
   listSaves(): Promise<SaveInfo[]>;
-  deleteSave(slot?: string): void;
+  deleteSave(slot?: string): Promise<void>;
   exportSave(slot?: string): Promise<SaveExport | null>;
   importSave(data: unknown, slot?: string): Promise<SaveInfo>;
   visited(name?: string): number;
@@ -343,12 +343,12 @@ function createStoryAPI(): StoryAPI {
       useStoryStore.getState().restart();
     },
 
-    save(slot?: string, custom?: Record<string, unknown>): void {
-      useStoryStore.getState().save(slot, custom);
+    save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
+      return useStoryStore.getState().save(slot, custom);
     },
 
-    load(slot?: string): void {
-      useStoryStore.getState().load(slot);
+    load(slot?: string): Promise<void> {
+      return useStoryStore.getState().load(slot);
     },
 
     hasSave(slot?: string): boolean {
@@ -363,8 +363,8 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().listSaves();
     },
 
-    deleteSave(slot?: string): void {
-      useStoryStore.getState().deleteSave(slot);
+    deleteSave(slot?: string): Promise<void> {
+      return useStoryStore.getState().deleteSave(slot);
     },
 
     exportSave(slot?: string): Promise<SaveExport | null> {

package/types/index.d.ts

@@ -541,11 +541,18 @@ export interface StoryAPI {
   /** Restart the story from the beginning. */
   restart(): void;
 
-  /** Save the current state. Pass `slot` for a named save, `custom` for metadata. */
-  save(slot?: string, custom?: Record<string, unknown>): void;
+  /**
+   * Save the current state. Pass `slot` for a named save, `custom` for metadata.
+   * Resolves once the save is persisted (after `aftersave` handlers ran and
+   * `hasSave(slot)` is true); rejects if persisting fails.
+   */
+  save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
 
-  /** Load a saved state (quick load). */
-  load(slot?: string): void;
+  /**
+   * Load a saved state (quick load). Resolves once the loaded state is applied
+   * (immediately if the slot is empty); rejects if loading fails.
+   */
+  load(slot?: string): Promise<void>;
 
   /** Check whether a save exists. */
   hasSave(slot?: string): boolean;
@@ -556,8 +563,11 @@ export interface StoryAPI {
   /** List metadata for all known save slots. */
   listSaves(): Promise<SaveInfo[]>;
 
-  /** Delete a save by slot name. */
-  deleteSave(slot?: string): void;
+  /**
+   * Delete a save by slot name. Resolves once the save is removed and
+   * `hasSave(slot)` is false; rejects if deleting fails.
+   */
+  deleteSave(slot?: string): Promise<void>;
 
   /**
    * Export the save in a slot as a portable object (plain JSON).