@ryupold/vode 1.8.12 → 1.9.0

package/src/state-context.ts

@@ -1,16 +1,10 @@
-import { AnimatedPatch, DeepPartial, Patchable, PatchableState, RenderPatch } from "./vode";
+import { DeepPartial, Patchable, PatchableState, RenderPatch } from "./vode";
 
 /**
  * State context for type-safe access and manipulation of nested state paths
  * while still be able to access the parent state. 
  */
-export interface StateContext<S extends Patchable<S>, SubState> extends SubContext<SubState> {
-    /** 
-     * parent state
-     * @see PatchableState<S>
-     */
-    get state(): S;
-}
+export interface StateContext<S extends Patchable<S>, SubState> extends SubContext<SubState> { }
 
 /**
  * State context for type-safe access and manipulation of nested sub-state values without knowledge of the parent state.
@@ -52,43 +46,56 @@ export type ProxySubContext<SubState> = SubContext<SubState> & {
     : SubContext<SubState[K]>
 };
 
+type ProxyState<SubState> = SubState & {
+    [K in keyof SubState]-?: NonNullable<SubState[K]> extends object | null
+    ? ProxyState<NonNullable<SubState[K]>>
+    : SubState[K]
+};
+
 /**
- * create a ProxyStateContext for type-safe dynamic access to nested state
- * 
- * @example
+ * Creates a `ProxyStateContext` for type-safe access and manipulation of nested state.
+ *
+ * There are two ways to reach a subcontext:
+ *
+ * **1. Property chaining** — traverse the proxy directly via property access:
  * ```typescript
- * const state = createState({
- *   user: {
- *    profile: {
- *     settings: { theme: 'dark', lang: 'en' }
- *   }
- * });
- * 
- * // Create a proxy context for the state
  * const ctx = context(state).user.profile.settings;
- * 
- * // Access nested state dynamically
- * const settings = ctx.get(); // { theme: 'dark', lang: 'en' }
- * 
- * // Update and trigger render
- * ctx.patch({ theme: 'light' });
- * 
- * // Update without render (silent mutation)
- * ctx.put({ lang: 'de' });
  * ```
- * 
- * @param state 
- * @returns 
+ *
+ * **2. Path producer function** — pass a callback that navigates 
+ * the state tree; needed if your intermediate path contains 'get', 'put' or 'patch' properties that would conflict with the context API:
+ * ```typescript
+ * const ctx = context(state, s => s.user.profile.settings);
+ * ```
+ *
+ * Both forms return a `ProxyStateContext` that supports the same operations:
+ * ```typescript
+ * ctx.get();                   // read current value
+ * ctx.patch({ theme: 'light' }); // update and trigger render
+ * ctx.put({ lang: 'de' });       // update without render (silent mutation)
+ * ```
+ *
+ * @param state - The root `PatchableState` to create a context for
+ * @param producePath - Optional path producer; receives a proxy of the state and should return the desired sub-node
+ * @returns A `ProxyStateContext` rooted at the given path, with further property-chain access available
  */
-export function context<S extends PatchableState>(state: S): ProxyStateContext<S, S> {
-    return new ProxyStateContextImpl<S, S>(state, []) as unknown as ProxyStateContext<S, S>;
+
+export function context<S extends PatchableState, SS = S>(state: S): ProxyStateContext<S, SS>;
+export function context<S extends PatchableState, SS>(state: S, producePath: (ctx: ProxyState<S>) => ProxyState<SS>): ProxyStateContext<S, SS>;
+export function context<S extends PatchableState, SS = S>(state: S, producePath?: (ctx: ProxyState<S>) => ProxyState<SS>): ProxyStateContext<S, SS> {
+    if (producePath) {
+        const proxy = producePath(proxyState<S>(state, [] as string[]));
+        const keys = (proxy as any)["___KeYs___"] as string[];
+        return new ProxyStateContextImpl<S, SS>(state, keys) as unknown as ProxyStateContext<S, SS>;
+    }
+    return new ProxyStateContextImpl<S, S>(state, []) as unknown as ProxyStateContext<S, SS>;
 }
 
 class ProxyStateContextImpl<S extends PatchableState, SubState>
     implements StateContext<S, SubState> {
 
     constructor(
-        public readonly state: S,
+        private readonly state: S,
         private readonly keys: string[]
     ) {
         function putDeep(value: SubState | DeepPartial<SubState> | undefined | null, target: S | DeepPartial<S>) {
@@ -150,8 +157,6 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
 
         return new Proxy(this, {
             get: (target, prop, receiver) => {
-                if (prop === 'state')
-                    return state;
 
                 if (prop === 'get')
                     return get;
@@ -162,10 +167,12 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
                 if (prop === 'patch')
                     return patch;
 
-
                 // otherwise return a new ProxyStateContext for nested access
-                const newKeys = [...target.keys, String(prop)];
+            const newKeys = [...keys, String(prop)];
                 return new ProxyStateContextImpl<S, any>(target.state, newKeys);
+            },
+            set: (target: this, p: string | symbol, newValue: any, receiver: any) => {
+                throw new Error("ProxyStateContext is not meant to be directly mutated. Use put() or patch() methods on the StateContext instead");
             }
         });
     }
@@ -174,3 +181,23 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
     put(value: SubState | DeepPartial<SubState>): void { }
     patch(value: SubState | DeepPartial<SubState> | DeepPartial<SubState>[]): void { }
 }
+
+
+function proxyState<S extends PatchableState>(
+    state: S,
+    keys: string[]
+) {
+    return new Proxy(state, {
+        get: (target, prop, receiver) => {
+            if (prop === "___KeYs___") {
+                return keys;
+            }
+
+            const newKeys = [...keys, String(prop)];
+            return proxyState<S>(state, newKeys);
+        },
+        set: (target: any, p: string | symbol, newValue: any, receiver: any) => {
+            throw new Error("ProxyState is not meant to be directly mutated");
+        }
+    });
+}

package/src/vode.ts

@@ -228,10 +228,10 @@ export function app<S extends PatchableState = PatchableState>(
 
     function renderDom(isAnimated: boolean) {
         const sw = performance.now();
-        const vom = dom(_vode.state);
-        _vode.vode = render<S>(_vode.state, container.parentElement as Element, 0, 0, _vode.vode, vom)!;
+        _vode.vode = render<S>(_vode.state, container.parentElement as Element, 0, 0, _vode.vode, dom(_vode.state))!;
 
-        if ((<ContainerNode<S>>container).tagName.toUpperCase() !== (vom[0] as Tag).toUpperCase()) { //the tag name was changed during render -> update reference to vode-app-root 
+        if ((<ContainerNode<S>>container).tagName.toLowerCase() !== (<Vode<S>>_vode.vode)[0].toLowerCase()) {
+            //the tag name was changed during render -> update reference to vode-app-root 
             container = _vode.vode.node as Element;
             (<ContainerNode<S>>container)._vode = _vode
         }
@@ -299,6 +299,13 @@ export function app<S extends PatchableState = PatchableState>(
         hydrate<S>(container, true) as AttachedVode<S>,
         dom(<S>state)
     )!;
+
+    // if during initial render the tag of the root vode was changed (catch or different Tag)
+    if (container.tagName.toLowerCase() !== (<Vode<S>>_vode.vode)[0].toLowerCase()) {
+        container = _vode.vode.node as Element;
+        (container as ContainerNode<S>)._vode = _vode;
+    }
+
     const continueRendering = _vode.stats.syncRenderPatchCount !== patchCountBefore;
     _vode.isRendering = 0;
     _vode.stats.syncRenderCount++;

package/test/tests-app.ts

@@ -120,8 +120,7 @@ export default {
 
         await state.patch([{ a: 10 }, { b: 20 }]);
 
-        await expect(state.a).toEqual(10);
-        await expect(state.b).toEqual(20);
+        await expect(state).toEqual({ a: 10, b: 20 });
     },
 
     "app(): multiple sequential patches both apply": async () => {

package/test/tests-catch.ts

@@ -1,5 +1,5 @@
 import { expect } from "./helper";
-import { app, createState, DIV, ARTICLE, SECTION, P } from "../index";
+import { app, createState, DIV, ARTICLE, SECTION, P, MAIN } from "../index";
 
 function setup() {
     const root = document.createElement("div");
@@ -157,4 +157,64 @@ export default {
             ]
         );
     },
+
+    "catch: bubbles up to the root component if deeply nested vodes dont catch it earlier": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        app(container, {}, () =>
+            [DIV,
+                {
+                    catch: (s: unknown, err: Error) => [DIV, `caught: ${err.message}`]
+                },
+
+                [MAIN,
+                    [SECTION,
+                        [ARTICLE, {
+                            onMount: () => {
+                                throw new Error("boom");
+                            }
+                        }],
+                    ],
+                ]
+            ]
+        );
+
+        await expect(container).toMatch(
+            [DIV, "caught: boom"],
+        );
+    },
+
+    "catch: if catching in root vode with different Tag -> container will be replaced": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        await expect(root.firstChild === container).toEqual(true);
+
+        app(container, {}, () =>
+            [DIV,
+                {
+                    catch: (s: unknown, err: Error) => [P, `caught: ${err.message}`]
+                },
+
+                [MAIN,
+                    [SECTION,
+                        [ARTICLE, {
+                            onMount: () => {
+                                throw new Error("boom");
+                            }
+                        }],
+                    ],
+                ]
+            ]
+        );
+
+        await expect(root.firstChild === container).toEqual(false);
+
+        await expect(root.firstChild).toMatch(
+            [P, "caught: boom"],
+        );
+    },
 };

package/test/tests-patch-advanced.ts

@@ -11,8 +11,8 @@ function setup() {
 export default {
     "patch(): generator function yields multiple state updates": async () => {
         const container = setup();
-        const state: any = createState({ count: 0 });
-        app(container, state, (s: any) => [DIV, String(s.count)]);
+        const state = createState({ count: 0 });
+        app<typeof state>(container, state, (s) => [DIV, String(s.count)]);
 
         await expect(state.count).toEqual(0);
 
@@ -30,8 +30,8 @@ export default {
 
     "patch(): async generator yields over time": async () => {
         const container = setup();
-        const state: any = createState({ phase: "start", value: 0 });
-        app(container, state, (s: any) => [DIV, s.phase, String(s.value)]);
+        const state = createState({ phase: "start", value: 0 });
+        app<typeof state>(container, state, (s) => [DIV, s.phase, String(s.value)]);
 
         await expect(state.phase).toEqual("start");
 
@@ -53,38 +53,37 @@ export default {
 
     "patch(): Promise resolves and applies patch": async () => {
         const container = setup();
-        const state: any = createState({ msg: "before" });
-        app(container, state, (s: any) => [DIV, s.msg]);
-
-        state.patch(Promise.resolve({ msg: "after" }));
+        const state = createState({ msg: "before" });
+        app<typeof state>(container, state, (s) => [DIV, s.msg]);
 
-        await delay(10);
+        await state.patch(Promise.resolve({ msg: "after" }));
 
-        await expect(state.msg).toEqual("after");
+        await expect(state).toEqual({ msg: "after" });
         await expect(container).toMatch([DIV, "after"]);
     },
 
     "patch(): array with empty patches applies nothing": async () => {
         const container = setup();
-        const state: any = createState({ x: 1, y: 2 });
-        app(container, state, (s: any) => [DIV]);
+        const state = createState({ x: 1, y: 2 });
+        app(container, state, (s) => [DIV]);
+
+        await state.patch([{}, {}]);
 
-        state.patch([{}, {}]);
-        await expect(state.x).toEqual(1);
-        await expect(state.y).toEqual(2);
+        await delay(10);
+        await expect(state).toEqual({ x: 1, y: 2 });
     },
 
     "patch(): array with null/undefined items skips them": async () => {
         const container = setup();
-        const state: any = createState({ x: 0, y: 0 });
-        app(container, state, (s: any) => [DIV, String(s.x), String(s.y)]);
+        const state = createState({ x: 0, y: 0 });
+        app<typeof state>(container, state, (s) => [DIV, String(s.x), String(s.y)]);
 
         state.patch([null, { x: 10 }, undefined, { y: 20 }]);
 
-        await delay(10);
-
-        await expect(state.x).toEqual(10);
-        await expect(state.y).toEqual(20);
+        await expect(() => expect(state.x).toEqual(10))
+            .toSucceedAsync();
+        await expect(() => expect(state.y).toEqual(20))
+            .toSucceedAsync();
     },
 
     "patch(): returns Promise for generator functions, can be awaited": async () => {

package/test/tests-state-context.ts

@@ -1,17 +1,9 @@
 import { expect } from "./helper";
-import { context, ProxySubContext } from "../src/state-context";
+import { context } from "../src/state-context";
 import { createState } from "../src/vode";
 
 export default {
-    "StateContext.state: returns the state reference": async () => {
-        const state = createState({ x: 10 });
-        const ctx = context(state);
-
-        await expect((ctx).state === state)
-            .toEqual(true);
-    },
-
-    "StateContext.get() returns whole state": async () => {
+    "context(s)...get(): returns whole state": async () => {
         const state = createState({ a: 1, b: 2 });
         const ctx = context(state);
 
@@ -20,7 +12,7 @@ export default {
     },
 
 
-    "StateContext.get(): deep nested": async () => {
+    "context(s)...get(): deep nested": async () => {
         const state = createState({ a: { b: { c: 42 } } });
         const ctx = context(state);
 
@@ -28,7 +20,7 @@ export default {
             .toEqual(42);
     },
 
-    "StateContext.get(): missing nested path returns undefined": async () => {
+    "context(s)...get(): missing nested path returns undefined": async () => {
         const state = createState({ a: {} });
         const ctx = context(state);
 
@@ -36,7 +28,7 @@ export default {
             .toEqual(undefined);
     },
 
-    "StateContext.put(): silently mutates state": async () => {
+    "context(s)...put(): silently mutates state": async () => {
         const state = createState({ a: { b: 1 } });
         const ctx = context(state);
         ctx.a.b.put(2);
@@ -45,7 +37,7 @@ export default {
             .toEqual(2);
     },
 
-    "StateContext.put() on nested object replaces the sub-object": async () => {
+    "context(s)...put(): on nested object replaces the sub-object": async () => {
         const state = createState({ a: { b: { x: 1, y: 2 } } });
         const ctx = context(state);
         ctx.a.b.put({ y: 99 });
@@ -54,7 +46,7 @@ export default {
             .toEqual({ y: 99 });
     },
 
-    "StateContext.put() at root level with empty keys": async () => {
+    "context(s)...put(): at root level with empty keys": async () => {
         const state = createState({ a: 1, b: 2 });
         const ctx = context(state);
         ctx.put({ b: undefined });
@@ -63,7 +55,7 @@ export default {
             .toEqual({ a: 1 });
     },
 
-    "StateContext.patch(): calls state.patch with proper deep partial": async () => {
+    "context(s)...patch(): calls state.patch with proper deep partial": async () => {
         const state = createState({ a: { b: 1 } });
         const ctx = context(state);
         ctx.a.b.patch(2);
@@ -76,7 +68,7 @@ export default {
             .toEqual({ a: { b: 2 } });
     },
 
-    "StateContext.patch(): async wraps in array": async () => {
+    "context(s)...patch(): async wraps in array": async () => {
         const state = createState({ a: { b: 1 } });
         const ctx = context(state);
         ctx.a.b.patch(2, true);
@@ -91,7 +83,7 @@ export default {
             .toEqual({ a: { b: 2 } });
     },
 
-    "StateContext.patch() on nested deep path three levels": async () => {
+    "context(s)...patch(): on nested deep path three levels": async () => {
         const state = createState({ x: { y: { z: 0 } } });
         const ctx = context(state);
         ctx.x.y.z.patch(100);
@@ -104,7 +96,7 @@ export default {
             .toEqual({ x: { y: { z: 100 } } });
     },
 
-    "StateContext.put() with intermediate null creates objects along the path": async () => {
+    "context(s)...put(): with intermediate null creates objects along the path": async () => {
         const state = createState({ a: null as { b: number } | null });
         const ctx = context(state);
 
@@ -116,7 +108,7 @@ export default {
         await expect(state.a?.b).toEqual(undefined);
     },
 
-    "StateContext.put() with three-level intermediate null": async () => {
+    "context(s)...put(): with three-level intermediate null": async () => {
         const state = createState({ a: null as { b: { c: number } } | null });
         const ctx = context(state);
 
@@ -125,7 +117,7 @@ export default {
         await expect(state.a?.b.c).toEqual(99);
     },
 
-    "StateContext.put() with multiple intermediate nulls": async () => {
+    "context(s)...put(): with multiple intermediate nulls": async () => {
         const state = createState({ a: { x: null as { z: string } | null, y: 1 } });
         const ctx = context(state);
 
@@ -135,11 +127,171 @@ export default {
         await expect(state.a.y).toEqual(1);
     },
 
-    "StateContext.put() merges into existing object properties via Object.assign": async () => {
+    "context(s)...put(): merges into existing object properties via Object.assign": async () => {
         const state = createState({ items: { count: 0, name: "test", hidden: false } });
         const ctx = context(state);
-        // Line 110-111: when existing value is object and new value is object, Object.assign merges
         ctx.items.put({ count: 5 });
         await expect(state.items).toEqual({ count: 5, name: "test", hidden: false });
     },
+
+    "context(state, s => s).get(): returns whole state": async () => {
+        const state = createState({ a: 1, b: 2 });
+        const ctx = context(state, s => s);
+
+        await expect(ctx.get())
+            .toEqual({ a: 1, b: 2 });
+    },
+
+    "context(state, s => s.a.b.c).get(): deep nested": async () => {
+        const state = createState({ a: { b: { c: 42 } } });
+        const ctx = context(state, s => s.a.b.c);
+
+        await expect(ctx.get())
+            .toEqual(42);
+    },
+
+    "context(state, s => s.a.b).get(): missing nested path returns undefined": async () => {
+        const state = createState({ a: {} });
+        const ctx = context(state, s => (s.a as any).b);
+
+        await expect(ctx.get())
+            .toEqual(undefined);
+    },
+
+    "context(state, s => s.a.b).put(): silently mutates state": async () => {
+        const state = createState({ a: { b: 1 } });
+        const ctx = context(state, s => s.a.b);
+        ctx.put(2);
+
+        await expect(state.a.b)
+            .toEqual(2);
+    },
+
+    "context(state, s => s.a.b).put(): on nested object replaces the sub-object": async () => {
+        const state = createState({ a: { b: { x: 1, y: 2 } } });
+        const ctx = context(state, s => s.a.b);
+        ctx.put({ y: 99 });
+
+        await expect(state.a.b)
+            .toEqual({ y: 99 });
+    },
+
+    "context(state, s => s).put(): at root level with empty keys": async () => {
+        const state = createState({ a: 1, b: 2 });
+        const ctx = context(state, s => s);
+        ctx.put({ b: undefined });
+
+        await expect(state)
+            .toEqual({ a: 1 });
+    },
+
+    "context(state, s => s.a.b).patch(): calls state.patch with proper deep partial": async () => {
+        const state = createState({ a: { b: 1 } });
+        const ctx = context(state, s => s.a.b);
+        ctx.patch(2);
+
+        const patches = (state as any).patch.initialPatches;
+
+        await expect(patches.length)
+            .toEqual(1);
+        await expect(patches[0])
+            .toEqual({ a: { b: 2 } });
+    },
+
+    "context(state, s => s.a.b).patch(): async wraps in array": async () => {
+        const state = createState({ a: { b: 1 } });
+        const ctx = context(state, s => s.a.b);
+        ctx.patch(2, true);
+
+        const patches = (state as any).patch.initialPatches;
+
+        await expect(patches.length)
+            .toEqual(1);
+        await expect(Array.isArray(patches[0]))
+            .toEqual(true);
+        await expect(patches[0][0])
+            .toEqual({ a: { b: 2 } });
+    },
+
+    "context(state, s => s.x.y.z).patch(): on nested deep path three levels": async () => {
+        const state = createState({ x: { y: { z: 0 } } });
+        const ctx = context(state, s => s.x.y.z);
+        ctx.patch(100);
+
+        const patches = (state as any).patch.initialPatches;
+
+        await expect(patches.length)
+            .toEqual(1);
+        await expect(patches[0])
+            .toEqual({ x: { y: { z: 100 } } });
+    },
+
+    "context(state, s => s.x).y.z: continue proxy sub-state targeting": async () => {
+        const state = createState({ x: { y: { z: 0 } } });
+        const ctx = context(state, s => s.x).y.z;
+        ctx.patch(100);
+
+        const patches = (state as any).patch.initialPatches;
+
+        await expect(patches.length)
+            .toEqual(1);
+        await expect(patches[0])
+            .toEqual({ x: { y: { z: 100 } } });
+    },
+
+    "context(state, s => s.a.b).put(): with intermediate null creates objects": async () => {
+        const state = createState({ a: null as { b: number } | null });
+        const ctx = context(state, s => s.a.b);
+
+        ctx.put(42);
+        await expect(state.a?.b).toEqual(42);
+    },
+
+    "context(state, s => s.a.b.c).put(): with three-level intermediate null": async () => {
+        const state = createState({ a: null as { b: { c: number } } | null });
+        const ctx = context(state, s => s.a.b.c);
+
+        ctx.put(99);
+
+        await expect(state.a?.b.c).toEqual(99);
+    },
+
+    "context(state, s => s.a.x.z).put(): with multiple intermediate nulls": async () => {
+        const state = createState({ a: { x: null as { z: string } | null, y: 1 } });
+        const ctx = context(state, s => s.a.x.z);
+
+        ctx.put("deep");
+
+        await expect(state.a.x?.z).toEqual("deep");
+        await expect(state.a.y).toEqual(1);
+    },
+
+    "context(state, s => s.items).put(): merges into existing object properties via Object.assign": async () => {
+        const state = createState({ items: { count: 0, name: "test", hidden: false } });
+        const ctx = context(state, s => s.items);
+        ctx.put({ count: 5 });
+        await expect(state.items).toEqual({ count: 5, name: "test", hidden: false });
+    },
+
+    "context(state, s => s.get|put|patch...): 'get','put','patch' as intermediate properties without conflict": async () => {
+        const state = createState({
+            endpoints: {
+                get: { count: 1 },
+                put: { count: 2 },
+                patch: { count: 3 }
+            }
+        });
+
+        const getCtx = context(state, s => s.endpoints.get);
+        await expect(getCtx.get()).toEqual({ count: 1 });
+
+        const putCtx = context(state, s => s.endpoints.put);
+        putCtx.put({ count: 99 });
+        await expect(state.endpoints.put).toEqual({ count: 99 });
+
+        const patchCtx = context(state, s => s.endpoints.patch);
+        patchCtx.patch({ count: 42 });
+        const patches = (state as any).patch.initialPatches;
+        await expect(patches[0]).toEqual({ endpoints: { patch: { count: 42 } } });
+    },
 };