@novely/core 0.52.0-next.1 → 0.52.0

package/dist/index.d.ts

@@ -66,10 +66,6 @@ type CustomActionHandle = {
      * Function that will give action root (element which you should add to the screen because custom actions rendered into that element)
      */
     setMountElement: (mountElement: null | HTMLDivElement) => void;
-    /**
-     * Function that will give you clean function provided by custom action.
-     */
-    setClear: (clear: () => void) => void;
 };
 type AudioHandle = {
     stop: () => void;
@@ -222,7 +218,7 @@ type RendererInit<$Language extends Lang, $Characters extends Record<string, Cha
     preview: (save: Save<State>, name: string) => Promise<RendererInitPreviewReturn>;
     removeContext: (name: string) => void;
     getStateFunction: (context: string) => StateFunction<State>;
-    clearCustomAction: (ctx: Context, customAction: CustomHandler) => void;
+    clearCustomActionsAtContext: (ctx: Context) => void;
     getLanguageDisplayName: (lang: Lang) => string;
     getCharacterColor: (character: string) => string;
     getCharacterAssets: (character: string, emotion: string) => string[];
@@ -613,15 +609,6 @@ type StateFunction<S extends State> = {
     (value: DeepPartial<S> | ((prev: S) => S)): void;
     (): S;
 };
-/**
- * @deprecated `EngineTypes` should be used instead
- */
-type TypeEssentials<$Lang extends Lang, $State extends State, $Data extends Data, $Characters extends Record<string, Character<$Lang>>> = {
-    readonly l: $Lang | null;
-    readonly s: $State | null;
-    readonly d: $Data | null;
-    readonly c: $Characters | null;
-};
 type EngineTypes<$Lang extends Lang = Lang, $State extends State = State, $Data extends Data = Data, $Characters extends Record<string, Character<$Lang>> = Record<string, Character<$Lang>>> = {
     readonly l: $Lang;
     readonly s: $State;
@@ -685,9 +672,9 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
      */
     getDomNodes: CustomHandlerFunctionGetFn;
     /**
-     * Function to get current Save. It can be mutated.
+     * Function to get current Save. It can be mutated. Only use it when you know what you do
      *
-     * Only use it when you know what you do
+     * @deprecated
      */
     getSave: () => Save<S>;
     /**
@@ -700,27 +687,68 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     contextKey: string;
     /**
      * Function to work with custom action's state
+     *
+     * @example
+     * ```ts
+     * type Data = { name: string };
+     *
+     * const handler: CustomHandler = async ({ data }) => {
+     *   const _data = data<Data>();
+     *
+     *   if (!_data.name) {
+     *     _data.name = 'Mr. Crabs'
+     *   }
+     *
+     *   data<Data>().name // 'Mr. Crabs'
+     *
+     *   data<Data>() == _data // true
+     *
+     *   // passing object will replace object
+     *   data<Data>({ name: 'Mr. Crabs' })
+     *   data<Data>() == _data // false
+     * }
+     * ```
      */
     data: CustomHandlerGetResultDataFunction;
     /**
      * Function to access data stored at specific key.
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ dataAtKey }) => {
+     *   // peek at data at action with key 'action-2'
+     *   console.log(dataAtKey('action-2'))
+     * }
+     *
+     * handler.key = 'action-1'
+     * ```
      * @deprecated
      */
     dataAtKey: <T extends Record<string, unknown>>(key: string) => T | null;
     /**
-     * Function to set cleanup handler
+     * Function to register cleanup callbacks (executed in reverse order of registration).
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ clear, paused }) => {
+     *   const unsubscribe = paused.subscribe((paused) => {
+     *
+     *   })
+     *
+     *   clear(paused);
+     * }
+     * ```
      */
     clear: (fn: () => void) => void;
     /**
-     * Remove's custom handler instance
+     * It will call all clear actions and remove HTML element from `getDomNodes` function
      */
     remove: () => void;
     /**
-     * Context's state function
+     * State function
      */
     state: StateFunction<S>;
     /**
-     * Game flags (aka game states)
+     * Game state
      */
     flags: {
         restoring: boolean;
@@ -733,10 +761,27 @@ type CustomHandlerFunctionParameters<L extends string, S extends State> = {
     lang: L;
     /**
      * Function to replace template content
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ state, templateReplace }) => {
+     *   const text = templateReplace({ en: '' }, state())
+     * }
+     * ```
      */
     templateReplace: (content: TextContent<L, State>, values?: State) => string;
     /**
      * Is game currently paused
+     *
+     * @example
+     * ```ts
+     * const handler: CustomHandler = async ({ clear, paused }) => {
+     *   const unsubscribe = paused.subscribe((paused) => {
+     *     // Here you can pause/resume animations, sounds, etc, etc
+     *   })
+     *
+     *   clear(paused);
+     * }
      */
     paused: Derived<boolean>;
 };
@@ -767,17 +812,6 @@ type CustomHandlerInfo = CustomHandlerCalling & {
      * When true interacting with it will be saved in history
      */
     requireUserAction?: boolean;
-    /**
-     * When player is going back we clear every custom action. But we can ignore clearing that.
-     */
-    skipClearOnGoingBack?: boolean;
-    /**
-     * When goingBack the restoring method is used. In that case, current actions array changes
-     *
-     * [1, 2, 3] changes to [1, 2]
-     * When you don't want 3'rd action to be cleared use this
-     */
-    skipClearOnRestore?: boolean;
     /**
      * Id by which we will determine what action is which
      */
@@ -1001,19 +1035,6 @@ declare const novely: <$Language extends string, $Characters extends Record<stri
      * ```
      */
     data: StateFunction<$Data>;
-    /**
-     * Used in combination with type utilities
-     * @deprecated Use `engine.types` instead
-     * @example
-     * ```ts
-     * import type { ConditionParams, StateFunction } from '@novely/core';
-     *
-     * const conditionCheck = (state: StateFunction<ConditionParams<typeof engine.typeEssintials>>) => {
-     *   return state.age >= 18;
-     * }
-     * ```
-     */
-    typeEssentials: TypeEssentials<$Language, $State, $Data, $Characters>;
     /**
      * Used in combination with type utilities
      * @example
@@ -1157,4 +1178,4 @@ declare const pauseOnBlur: (engine: {
     unsubscribe: () => void;
 };
 
-export { type ActionChoiceChoice, type ActionChoiceChoiceObject, type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterAssetSizes, type CharacterHandle, type CharactersData, type ChoiceCheckFunction, type ChoiceCheckFunctionProps, type ChoiceOnSelectFunction, type ChoiceOnSelectFunctionProps, type ChoiceParams, type ConditionCheckFunction, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunction, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type CustomHandlerInfo, type Data, type DeepPartial, type DefaultActionProxy, type Derived, EN, type Emotions, type EngineTypes, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type Path, type PathItem, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type StorageAdapter, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypeEssentials, type TypesFromEngine, type TypewriterSpeed, type ValidAction, asset, extendAction, novely, pauseOnBlur, storageAdapterLocal };
+export { type ActionChoiceChoice, type ActionChoiceChoiceObject, type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterAssetSizes, type CharacterHandle, type CharactersData, type ChoiceCheckFunction, type ChoiceCheckFunctionProps, type ChoiceOnSelectFunction, type ChoiceOnSelectFunctionProps, type ChoiceParams, type ConditionCheckFunction, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunction, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type CustomHandlerInfo, type Data, type DeepPartial, type DefaultActionProxy, type Derived, EN, type Emotions, type EngineTypes, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type Path, type PathItem, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type StorageAdapter, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type TranslationActions, type TypesFromEngine, type TypewriterSpeed, type ValidAction, asset, extendAction, novely, pauseOnBlur, storageAdapterLocal };

package/dist/index.js

@@ -122,6 +122,7 @@ var MAIN_CONTEXT_KEY = "$MAIN";
 // src/shared.ts
 var STACK_MAP = /* @__PURE__ */ new Map();
 var CUSTOM_ACTION_MAP = /* @__PURE__ */ new Map();
+var CUSTOM_ACTION_CLEANUP_MAP = /* @__PURE__ */ new Map();
 var PRELOADED_ASSETS = /* @__PURE__ */ new Set();
 var ASSETS_TO_PRELOAD = /* @__PURE__ */ new Set();
 
@@ -922,7 +923,7 @@ var capitalize = (str) => {
   return str[0].toUpperCase() + str.slice(1);
 };
 
-// src/utilities/functions.ts
+// src/utilities/noop.ts
 var noop = () => {
 };
 
@@ -997,6 +998,7 @@ var immutable = (value) => {
 };
 
 // src/custom-action.ts
+import { once as once2 } from "es-toolkit/function";
 var createCustomActionNode = (id) => {
   const div = document.createElement("div");
   div.setAttribute("data-id", id);
@@ -1008,7 +1010,6 @@ var getCustomActionHolder = (ctx, fn) => {
     return cached;
   }
   const holder = {
-    cleanup: noop,
     node: null,
     fn,
     localData: {}
@@ -1016,22 +1017,50 @@ var getCustomActionHolder = (ctx, fn) => {
   CUSTOM_ACTION_MAP.set(ctx.id + fn.key, holder);
   return holder;
 };
+var getCustomActionCleanupHolder = (ctx) => {
+  const existing = CUSTOM_ACTION_CLEANUP_MAP.get(ctx.id);
+  if (existing) {
+    return existing;
+  }
+  const holder = [];
+  CUSTOM_ACTION_CLEANUP_MAP.set(ctx.id, holder);
+  return holder;
+};
+var cleanCleanupSource = ({ list }) => {
+  while (list.length) {
+    try {
+      list.pop()();
+    } catch (e) {
+      console.error(e);
+    }
+  }
+};
 var handleCustomAction = (ctx, fn, {
   lang,
   state,
   setMountElement,
-  setClear,
   remove: renderersRemove,
   getStack: getStack2,
   templateReplace,
   paused
 }) => {
   const holder = getCustomActionHolder(ctx, fn);
-  const flags = {
-    ...ctx.meta
+  const cleanupHolder = getCustomActionCleanupHolder(ctx);
+  const cleanupNode = () => {
+    if (!cleanupHolder.some((item) => item.fn.id === fn.id && item.fn.key === fn.key)) {
+      holder.node = null;
+      setMountElement(null);
+    }
+  };
+  const cleanupSource = {
+    fn,
+    list: [],
+    node: cleanupNode
   };
+  cleanupHolder.push(cleanupSource);
   const getDomNodes = (insert = true) => {
     if (holder.node || !insert) {
+      setMountElement(holder.node);
       return {
         element: holder.node,
         root: ctx.root
@@ -1045,15 +1074,7 @@ var handleCustomAction = (ctx, fn, {
     };
   };
   const clear = (func) => {
-    setClear(
-      holder.cleanup = () => {
-        func();
-        holder.node = null;
-        holder.cleanup = noop;
-        setMountElement(null);
-        setClear(noop);
-      }
-    );
+    cleanupSource.list.push(once2(func));
   };
   const data = (updatedData) => {
     if (updatedData) {
@@ -1062,7 +1083,9 @@ var handleCustomAction = (ctx, fn, {
     return holder.localData;
   };
   const remove = () => {
-    holder.cleanup();
+    cleanCleanupSource(cleanupSource);
+    holder.node = null;
+    setMountElement(null);
     renderersRemove();
   };
   const stack = getStack2(ctx);
@@ -1070,7 +1093,7 @@ var handleCustomAction = (ctx, fn, {
     return stack.value;
   };
   return fn({
-    flags,
+    flags: ctx.meta,
     lang,
     state,
     data,
@@ -1082,7 +1105,7 @@ var handleCustomAction = (ctx, fn, {
     getDomNodes,
     getSave,
     contextKey: ctx.id,
-    paused: flags.preview ? immutable(false) : paused
+    paused: ctx.meta.preview ? immutable(false) : paused
   });
 };
 
@@ -1607,13 +1630,7 @@ var novely = ({
       filter: false,
       referGuarded
     });
-    const {
-      run,
-      keep: { keep, characters: characters2, audio: audio2 }
-    } = createQueueProcessor(queue, {
-      skip,
-      skipPreserve
-    });
+    const cleanupHolder = getCustomActionCleanupHolder(context);
     if (previous) {
       const { queue: prevQueue } = await getActionsFromPath({
         story,
@@ -1621,17 +1638,37 @@ var novely = ({
         filter: false,
         referGuarded
       });
-      for (let i = prevQueue.length - 1; i > queue.length - 1; i--) {
-        const element = prevQueue[i];
-        if (!isAction(element)) {
-          continue;
+      const futures = [];
+      const isFromDifferentBranches = previous[0][0][1] !== path[0][1];
+      const end = isFromDifferentBranches ? 0 : queue.length - 1;
+      for (let i = prevQueue.length - 1; i >= end; i--) {
+        const [action2, fn] = prevQueue[i];
+        if (action2 === "custom") {
+          futures.push(fn);
         }
-        const [action2, fn] = element;
-        if (action2 === "custom" && !fn.skipClearOnRestore) {
-          clearCustomAction(context, fn);
+      }
+      futures.reverse();
+      const nodeCleanup = /* @__PURE__ */ new Set();
+      for (const future of futures) {
+        inner: for (let i = cleanupHolder.length - 1; i >= 0; i--) {
+          const item = cleanupHolder[i];
+          if (future === item.fn) {
+            cleanCleanupSource(item);
+            nodeCleanup.add(item.node);
+            cleanupHolder.splice(i, 1);
+            break inner;
+          }
         }
       }
+      nodeCleanup.forEach((f) => f());
     }
+    const {
+      run,
+      keep: { keep, characters: characters2, audio: audio2 }
+    } = createQueueProcessor(queue, {
+      skip,
+      skipPreserve
+    });
     if (context.meta.goingBack) {
       match("clear", [keep, characters2, audio2], {
         ctx: context,
@@ -1647,6 +1684,11 @@ var novely = ({
         return;
       }
       const [action2, ...props] = item;
+      if (action2 === "custom") {
+        if (cleanupHolder.some((holder) => holder.fn === props[0])) {
+          return;
+        }
+      }
       return match(action2, props, {
         ctx: context,
         data: latest[1]
@@ -1681,6 +1723,7 @@ var novely = ({
       save("auto");
     }
     stack.clear();
+    clearCustomActionsAtContext(ctx);
     ctx.clear(EMPTY_SET, EMPTY_SET, { music: EMPTY_SET, sounds: EMPTY_SET }, noop);
     renderer.ui.showScreen("mainmenu");
     ctx.audio.destroy();
@@ -1780,8 +1823,15 @@ var novely = ({
     }
     return capitalize(language.nameOverride || getIntlLanguageDisplayName(lang));
   };
-  const clearCustomAction = (ctx, fn) => {
-    getCustomActionHolder(ctx, fn).cleanup();
+  const clearCustomActionsAtContext = (ctx) => {
+    const cleanupHolder = getCustomActionCleanupHolder(ctx);
+    const nodeCleanup = /* @__PURE__ */ new Set();
+    for (const item of cleanupHolder) {
+      cleanCleanupSource(item);
+      nodeCleanup.add(item.node);
+    }
+    cleanupHolder.length = 0;
+    nodeCleanup.forEach((fn) => fn());
   };
   const getResourseTypeWrapper = (url) => {
     return getResourseType({
@@ -1836,7 +1886,7 @@ var novely = ({
     preview,
     removeContext,
     getStateFunction,
-    clearCustomAction,
+    clearCustomActionsAtContext,
     languages,
     storageData,
     coreData,
@@ -2343,19 +2393,6 @@ var novely = ({
      * ```
      */
     data,
-    /**
-     * Used in combination with type utilities
-     * @deprecated Use `engine.types` instead
-     * @example
-     * ```ts
-     * import type { ConditionParams, StateFunction } from '@novely/core';
-     *
-     * const conditionCheck = (state: StateFunction<ConditionParams<typeof engine.typeEssintials>>) => {
-     *   return state.age >= 18;
-     * }
-     * ```
-     */
-    typeEssentials: {},
     /**
      * Used in combination with type utilities
      * @example