@mittwald/react-ghostmaker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mittwald CM Service GmbH & Co. KG and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/RenderComponent.js

@@ -0,0 +1,3 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { memo } from "react";
+export const RenderComponent = memo((props) => (_jsx(_Fragment, { children: props.render() })));

package/dist/esm/context.js

@@ -0,0 +1,4 @@
+import { createCascade } from "context";
+export const ghostFnContext = createCascade();
+const useGhostFnContext = () => ghostFnContext.use();
+export const getGhostId = () => useGhostFnContext()?.ghostId;

package/dist/esm/hash.js

@@ -0,0 +1,7 @@
+import { hash } from "object-code";
+const hashCache = new WeakMap();
+export const hashObject = (model) => {
+    const hashed = hashCache.get(model) ?? hash(model);
+    hashCache.set(model, hashed);
+    return hashed;
+};

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { makeGhost } from "./makeGhost";
+export { getGhostId } from "./context";
+export { invalidateGhostsById } from "./invalidate";
+export { registerModelIdentifier } from "./modelIdentifier";
+export * from "./maybeGhost";

package/dist/esm/invalidate.js

@@ -0,0 +1,17 @@
+import { matchQuery } from "@tanstack/react-query";
+import { getGhostId, queries } from "./queries";
+export const invalidateGhostsById = (queryClient, ghostId) => {
+    queryClient.invalidateQueries({
+        predicate: (query) => query.meta?.ghostId === ghostId,
+    });
+};
+export function invalidateGhosts(queryClient, model, chain) {
+    const queryKey = queries.ghostChain(model, chain);
+    const ghostId = getGhostId(queryKey);
+    queryClient.invalidateQueries({
+        predicate: (query) => query.meta?.ghostId === ghostId ||
+            matchQuery({
+                queryKey,
+            }, query),
+    });
+}

package/dist/esm/makeGhost.js

@@ -0,0 +1,71 @@
+import { createElement } from "react";
+import { isGhostMarker, transformFnProp, } from "./types";
+import { useGhostChain } from "./useGhostChain";
+import { RenderComponent } from "./RenderComponent";
+import { resolveGhostChain } from "./resolveGhostChain";
+import { invalidateGhosts } from "./invalidate";
+function buildGhostDeep(model, ghostChain) {
+    const target = (() => {
+        // Dummy function to allow ghosting function calls
+    });
+    const useQuery = (options) => useGhostChain(model, ghostChain, options);
+    const useGhostMethods = {
+        use: (options) => useQuery(options).value,
+        useGhost: useQuery,
+        render: (transform) => {
+            const render = () => {
+                const usedValue = useGhostMethods.use();
+                return transform ? transform(usedValue) : usedValue;
+            };
+            return createElement(RenderComponent, { render });
+        },
+        transform: (fn, dependencies) => {
+            ghostChain.push({
+                propName: transformFnProp,
+                args: [fn, dependencies],
+            });
+            return ghost;
+        },
+        invalidate: (queryClient) => {
+            invalidateGhosts(queryClient, model, ghostChain);
+        },
+    };
+    const ghost = new Proxy(target, {
+        get: ($, prop) => {
+            if (prop === isGhostMarker) {
+                return true;
+            }
+            if (prop in useGhostMethods) {
+                return useGhostMethods[prop];
+            }
+            if (prop === "then") {
+                return (resolve, reject) => resolveGhostChain(model, ghostChain).then(resolve).catch(reject);
+            }
+            if (prop === Symbol.toPrimitive) {
+                return (hint) => {
+                    if (hint === "string") {
+                        return "ReactGhostmakerFunction";
+                    }
+                    return null;
+                };
+            }
+            return buildGhostDeep(model, [
+                ...ghostChain,
+                {
+                    propName: String(prop),
+                },
+            ]);
+        },
+        apply: ($, $$, args) => {
+            const prevCallStackEntry = ghostChain[ghostChain.length - 1];
+            if (prevCallStackEntry) {
+                prevCallStackEntry.args = args;
+            }
+            return buildGhostDeep(model, ghostChain);
+        },
+    });
+    return ghost;
+}
+export function makeGhost(model) {
+    return buildGhostDeep(model, []);
+}

package/dist/esm/makeGhost.test-d.js

@@ -0,0 +1,25 @@
+import { expectTypeOf, test } from "vitest";
+import { ProjectGhost } from "./testMocks";
+test("return type is correct", () => {
+    const customerNameGhost = ProjectGhost.ofId("Project A")
+        .getDetailed()
+        .customer.getDetailed()
+        .getName();
+    expectTypeOf(customerNameGhost).toEqualTypeOf();
+});
+test("optional return type is correct", () => {
+    const projectGhost = ProjectGhost.ofId("Project A").findDetailed();
+    expectTypeOf(projectGhost).toEqualTypeOf();
+    expectTypeOf(projectGhost.customer).toEqualTypeOf();
+    const customerNameGhost = projectGhost.customer.getDetailed().getName();
+    expectTypeOf(customerNameGhost).toEqualTypeOf();
+    projectGhost.name.transform((name) => {
+        expectTypeOf(name).toEqualTypeOf();
+    });
+});
+test("transform return type is correct", () => {
+    const transformedToNumber = ProjectGhost.ofId("Project A")
+        .getDetailed()
+        .name.transform(() => 0);
+    expectTypeOf(transformedToNumber).toEqualTypeOf();
+});

package/dist/esm/makeGhost.test.js

@@ -0,0 +1,223 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { describe, expect, test, vitest, beforeEach } from "vitest";
+import { CustomerDetailed, CustomerGhost, Project, ProjectGhost, customerMocks, getCustomerNameGhostIds, projectMocks, } from "./testMocks";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { invalidateGhostsById } from "./invalidate";
+test("Pre Test", async () => {
+    const project = new Project("P1");
+    expect(projectMocks.getDetailed).toHaveBeenCalledTimes(0);
+    expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
+    const detailedProject = await project.getDetailed();
+    expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1);
+    expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
+    expect(detailedProject.name).toBe("Project P1");
+    const customer = await detailedProject.customer.getDetailed();
+    expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
+    expect(customer.id).toBe("C1");
+});
+describe("Await", () => {
+    test("functions are called lazy", async () => {
+        const transform = vitest.fn((name) => name);
+        const customerNameGhost = ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform(transform);
+        expect(projectMocks.getDetailed).toHaveBeenCalledTimes(0);
+        expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
+        expect(customerMocks.getName).toHaveBeenCalledTimes(0);
+        expect(transform).toHaveBeenCalledTimes(0);
+        await customerNameGhost;
+        expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1);
+        expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
+        expect(customerMocks.getName).toHaveBeenCalledTimes(1);
+        expect(transform).toHaveBeenCalledTimes(1);
+    });
+    test("simple usage", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName();
+        expect(customerName).toBe("Customer C1");
+    });
+    test("with transform", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform((name) => name.toUpperCase());
+        expect(customerName).toBe("CUSTOMER C1");
+    });
+    test("with undefined result in call stack", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .findDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform((name) => {
+            expect(name).toBeUndefined();
+            return name?.toUpperCase();
+        });
+        expect(customerName).toBeUndefined();
+    });
+    test("simple usage", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName();
+        expect(customerName).toBe("Customer C1");
+    });
+    test("with transform", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform((name) => name.toUpperCase());
+        expect(customerName).toBe("CUSTOMER C1");
+    });
+    test("with undefined result in call stack", async () => {
+        const customerName = await ProjectGhost.ofId("Project A")
+            .findDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform((name) => {
+            expect(name).toBeUndefined();
+            return name?.toUpperCase();
+        });
+        expect(customerName).toBeUndefined();
+    });
+});
+describe("Hooks", () => {
+    const queryClient = new QueryClient();
+    beforeEach(() => {
+        cleanup();
+        queryClient.clear();
+    });
+    async function renderHookWithSuspense(callback, options = {}) {
+        const { waitForSuspense = true } = options;
+        const result = {
+            current: undefined,
+        };
+        const Component = () => {
+            result.current = callback();
+            return _jsx("span", { "data-testid": "hook-ready" });
+        };
+        const ui = render(_jsx(Component, {}), {
+            wrapper: (props) => (_jsx(QueryClientProvider, { client: queryClient, children: props.children })),
+        });
+        if (waitForSuspense) {
+            await ui.findByTestId("hook-ready");
+        }
+        return {
+            ui,
+            result,
+            rerender: () => ui.rerender(_jsx(Component, {})),
+        };
+    }
+    test("functions are called lazy", async () => {
+        const transform = vitest.fn((name) => name);
+        const customerNameGhost = ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform(transform);
+        expect(projectMocks.getDetailed).toHaveBeenCalledTimes(0);
+        expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
+        expect(customerMocks.getName).toHaveBeenCalledTimes(0);
+        expect(transform).toHaveBeenCalledTimes(0);
+        await renderHookWithSuspense(() => customerNameGhost.useGhost());
+        expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1);
+        expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
+        expect(customerMocks.getName).toHaveBeenCalledTimes(1);
+        expect(transform).toHaveBeenCalledTimes(1);
+    });
+    test("simple usage", async () => {
+        const { result } = await renderHookWithSuspense(() => ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .use());
+        expect(result.current).toBe("Customer C1");
+        expect(customerMocks.getName).toHaveBeenCalledTimes(1);
+    });
+    test("simple usage with static function call", async () => {
+        const { result } = await renderHookWithSuspense(() => CustomerGhost.get("Customer A").use());
+        expect(result.current).toBeInstanceOf(CustomerDetailed);
+    });
+    test("with transform", async () => {
+        const { result } = await renderHookWithSuspense(() => ProjectGhost.ofId("Project A")
+            .getDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform((name) => name.toUpperCase())
+            .use());
+        expect(result.current).toBe("CUSTOMER C1");
+    });
+    test("with undefined result in call stack", async () => {
+        const transform = vitest.fn((name) => name);
+        const { result } = await renderHookWithSuspense(() => ProjectGhost.ofId("Project A")
+            .findDetailed()
+            .customer.getDetailed()
+            .getName()
+            .transform(transform)
+            .use());
+        expect(result.current).toBeUndefined();
+        expect(projectMocks.findDetailed).toHaveBeenCalledTimes(1);
+        expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
+        expect(customerMocks.getName).toHaveBeenCalledTimes(0);
+        expect(transform).toHaveBeenCalledTimes(1);
+        expect(transform).toHaveBeenCalledWith(undefined);
+    });
+    describe("Invalidation", () => {
+        test("useGhost.invalidate() triggers re-execution of all async methods", async () => {
+            const { result } = await renderHookWithSuspense(() => ProjectGhost.ofId("Project A")
+                .getDetailed()
+                .customer.getDetailed()
+                .getName()
+                .useGhost());
+            result.current?.invalidate();
+            await waitFor(() => expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2));
+            await waitFor(() => expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2));
+            await waitFor(() => expect(customerMocks.getName).toHaveBeenCalledTimes(2));
+        });
+        test("ghost.invalidate() triggers re-execution of all async methods", async () => {
+            const ghost = ProjectGhost.ofId("Project A")
+                .getDetailed()
+                .customer.getDetailed()
+                .getName();
+            await renderHookWithSuspense(() => ghost.use());
+            await waitFor(() => expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1));
+            ghost.invalidate(queryClient);
+            await waitFor(() => expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2));
+            await waitFor(() => expect(customerMocks.getName).toHaveBeenCalledTimes(2));
+        });
+        test("invalidateGhostsById() triggers re-execution of all async methods", async () => {
+            const ghost = ProjectGhost.ofId("Project A")
+                .getDetailed()
+                .customer.getDetailed()
+                .getName();
+            await renderHookWithSuspense(() => ghost.use());
+            await waitFor(() => expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1));
+            expect(getCustomerNameGhostIds.current).toBeDefined();
+            invalidateGhostsById(queryClient, getCustomerNameGhostIds.current);
+            await waitFor(() => expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2));
+            await waitFor(() => expect(customerMocks.getName).toHaveBeenCalledTimes(2));
+        });
+        test("ghost.invalidate() invalidates all dependent ghosts", async () => {
+            const ghost = ProjectGhost.ofId("Project A").getDetailed();
+            const specialGhost = ghost.customer.getDetailed();
+            await renderHookWithSuspense(() => specialGhost.use());
+            await waitFor(() => expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1));
+            ghost.invalidate(queryClient);
+            await waitFor(() => expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2));
+        });
+        test("ghost.invalidate() invalidate previous ghosts", async () => {
+            const ghost = ProjectGhost.ofId("Project A").getDetailed();
+            const specialGhost = ghost.customer.getDetailed();
+            await renderHookWithSuspense(() => ghost.use());
+            await waitFor(() => expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1));
+            specialGhost.invalidate(queryClient);
+            await expect(() => waitFor(() => expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2))).rejects.toThrow();
+        });
+    });
+});

package/dist/esm/maybeGhost/asGhost.js

@@ -0,0 +1,19 @@
+import { makeGhost } from "../makeGhost";
+import { isReactGhost } from "../types";
+export function asGhost(maybeGhost) {
+    if (isReactGhost(maybeGhost)) {
+        return maybeGhost;
+    }
+    return makeGhost(maybeGhost);
+}
+export function asGhostProps(props, keys) {
+    const fixupObjectEntry = (entry) => {
+        const [key, value] = entry;
+        const shouldFixup = keys === undefined || keys.includes(key);
+        if (shouldFixup) {
+            return [`${key}Ghost`, asGhost(value)];
+        }
+        return [key, value];
+    };
+    return Object.fromEntries(Object.entries(props).map(fixupObjectEntry));
+}

package/dist/esm/maybeGhost/index.js

@@ -0,0 +1,2 @@
+export * from "./asGhost";
+export * from "./types";

package/dist/esm/maybeGhost/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/maybeGhost/types.test-d.js

@@ -0,0 +1,16 @@
+import { describe, expectTypeOf, test } from "vitest";
+import { asGhostProps } from "./asGhost";
+describe("fixupMaybeReactGhostProps()", () => {
+    test("works for one prop", () => {
+        expectTypeOf(asGhostProps({})).toEqualTypeOf();
+    });
+    test("works for one optional prop", () => {
+        expectTypeOf(asGhostProps({})).toEqualTypeOf();
+    });
+    test("works for two prop", () => {
+        expectTypeOf(asGhostProps({})).toEqualTypeOf();
+    });
+    test("works for two selected props", () => {
+        expectTypeOf(asGhostProps({}, ["a", "b"])).toEqualTypeOf();
+    });
+});

package/dist/esm/modelIdentifier.js

@@ -0,0 +1,4 @@
+export const modelIdentifiers = [];
+export const registerModelIdentifier = (identifier) => {
+    modelIdentifiers.push(identifier);
+};

package/dist/esm/queries.js

@@ -0,0 +1,42 @@
+import is from "@sindresorhus/is";
+import { modelIdentifiers } from "./modelIdentifier";
+export const getObjectQueryKey = (something) => {
+    if (is.primitive(something)) {
+        return String(something);
+    }
+    const isObject = is.object(something);
+    const isClass = is.class(something);
+    const isFunction = is.function(something);
+    const objectName = isFunction
+        ? something.name
+        : isClass || isObject
+            ? something.constructor.name
+            : "unknown";
+    const thisModelIdentifiers = modelIdentifiers
+        .map((fn) => fn(something))
+        .filter(is.string)
+        .join(".");
+    if (thisModelIdentifiers) {
+        return `${objectName}@${thisModelIdentifiers}`;
+    }
+    return objectName;
+};
+export const ghostmakerQueryKey = "react-ghostmaker";
+export const getGhostId = (queryKey) => {
+    return queryKey.join(".");
+};
+export const queries = {
+    ghostmaker: () => [ghostmakerQueryKey],
+    model: (model) => [
+        ...queries.ghostmaker(),
+        getObjectQueryKey(model),
+    ],
+    chainItem: (chainItem) => {
+        const { propName, args = [] } = chainItem;
+        return [propName, ...args.map(getObjectQueryKey)];
+    },
+    ghostChain: (model, chain) => [
+        ...queries.model(model),
+        ...chain.flatMap(queries.chainItem),
+    ],
+};

package/dist/esm/resolveGhostChain.js

@@ -0,0 +1,33 @@
+import is, { assert } from "@sindresorhus/is";
+import { isReactGhost, transformFnProp, } from "./types";
+const resolveGhostChainItem = async (target, item) => {
+    const { propName, args } = item;
+    const model = target;
+    if (propName === transformFnProp) {
+        assert.array(args);
+        const transformFn = args[0];
+        assert.function(transformFn, "transform requires a mapping function");
+        const transformed = transformFn(target);
+        if (isReactGhost(transformed)) {
+            return transformed;
+        }
+        return transformed;
+    }
+    if (is.nullOrUndefined(model)) {
+        return undefined;
+    }
+    const property = model[propName];
+    if (args === undefined) {
+        return property;
+    }
+    assert.function(property);
+    const asyncFn = property.bind(target);
+    return await asyncFn(...args);
+};
+export const resolveGhostChain = async (initialModel, stack) => {
+    let result = initialModel;
+    for (const item of stack) {
+        result = await resolveGhostChainItem(result, item);
+    }
+    return result;
+};

package/dist/esm/testMocks.js

@@ -0,0 +1,94 @@
+import { beforeEach, vitest } from "vitest";
+import { getGhostId, makeGhost, registerModelIdentifier } from ".";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export let customerMocks;
+export let projectMocks;
+export const getCustomerNameGhostIds = {};
+beforeEach(() => {
+    vitest.resetAllMocks();
+    getCustomerNameGhostIds.current = undefined;
+    customerMocks = {
+        getName: vitest.fn().mockImplementation(() => {
+            getCustomerNameGhostIds.current = getGhostId();
+        }),
+        getDetailed: vitest
+            .fn()
+            .mockImplementation((id) => new CustomerDetailed(id, `Customer ${id}`)),
+    };
+    projectMocks = {
+        getName: vitest.fn(),
+        getDetailed: vitest
+            .fn()
+            .mockImplementation((id) => new ProjectDetailed(id, `Project ${id}`, "C1")),
+        findDetailed: vitest.fn().mockImplementation(() => undefined),
+        getStatus: vitest.fn(),
+    };
+});
+export class CustomerDetailed {
+    id;
+    name;
+    constructor(id, name) {
+        this.id = id;
+        this.name = name;
+    }
+    getName() {
+        customerMocks.getName();
+        return this.name;
+    }
+}
+export class Customer {
+    id;
+    constructor(id) {
+        this.id = id;
+    }
+    static ofId(id) {
+        return new Customer(id);
+    }
+    async getDetailed() {
+        return Customer.get(this.id);
+    }
+    static async get(id) {
+        await sleep(5);
+        return customerMocks.getDetailed(id);
+    }
+}
+export class Project {
+    id;
+    constructor(id) {
+        this.id = id;
+    }
+    static ofId(id) {
+        return new Project(id);
+    }
+    async getDetailed() {
+        await sleep(5);
+        return projectMocks.getDetailed(this.id);
+    }
+    async findDetailed() {
+        await sleep(5);
+        return projectMocks.findDetailed(this.id);
+    }
+}
+export class ProjectDetailed {
+    id;
+    name;
+    customer;
+    constructor(id, name, customerId) {
+        this.id = id;
+        this.name = name;
+        this.customer = new Customer(customerId);
+    }
+    getName() {
+        projectMocks.getName();
+        return this.name;
+    }
+    async getStatus() {
+        projectMocks.getStatus();
+        await sleep(5);
+        return "active";
+    }
+}
+export const ProjectGhost = makeGhost(Project);
+export const CustomerGhost = makeGhost(Customer);
+registerModelIdentifier((model) => model instanceof Project ? model.id : undefined);
+registerModelIdentifier((model) => model instanceof Customer ? model.id : undefined);

package/dist/esm/types.js

@@ -0,0 +1,7 @@
+import is from "@sindresorhus/is";
+export const transformFnProp = "___transformFn";
+export const isGhostMarker = "___ghostMarker";
+export function isReactGhost(something) {
+    return (is.function(something) &&
+        something[isGhostMarker] === true);
+}

package/dist/esm/useGhostChain.js

@@ -0,0 +1,78 @@
+import is, { assert } from "@sindresorhus/is";
+import { useMemo } from "react";
+import { transformFnProp, } from "./types";
+import { useQuery, useQueryClient, useSuspenseQuery, } from "@tanstack/react-query";
+import { getGhostId, queries } from "./queries";
+import { ghostFnContext } from "./context";
+import { invalidateGhosts } from "./invalidate";
+const useVoidQuery = () => useQuery({
+    queryKey: ["void"],
+    queryFn: () => Promise.resolve({
+        result: true,
+    }),
+});
+const useGhostChainItem = (target, item, options = {}, context) => {
+    const { propName, args } = item;
+    const model = target;
+    if (propName === transformFnProp) {
+        assert.array(args);
+        const transformFn = args[0];
+        assert.function(transformFn, "transform requires a mapping function");
+        const transformDependencies = args[1] ?? [];
+        assert.array(transformDependencies);
+        return useMemo(() => transformFn(model), [model, ...transformDependencies]);
+    }
+    if (is.nullOrUndefined(model)) {
+        if (args) {
+            useVoidQuery();
+        }
+        return model;
+    }
+    const modelPropertyName = propName;
+    const modelProperty = model[modelPropertyName];
+    context.queryKey.push(...queries.chainItem(item));
+    if (args === undefined) {
+        // no function call, just a property access
+        return modelProperty;
+    }
+    assert.function(modelProperty);
+    const modelFn = modelProperty.bind(model);
+    const queryKey = [...context.queryKey];
+    const query = useSuspenseQuery({
+        ...options,
+        queryKey: [...context.queryKey],
+        queryFn: async () => {
+            const modelFnWithContext = ghostFnContext.bind({ ghostId: context.ghostId }, modelFn);
+            const result = await modelFnWithContext(...args);
+            if (result instanceof Promise) {
+                return { result: await result };
+            }
+            return { result };
+        },
+        meta: {
+            ghostId: context.ghostId,
+            queryKey,
+        },
+    });
+    if (query.error) {
+        throw query.error;
+    }
+    return query.data.result;
+};
+export const useGhostChain = (initialModel, chain, options) => {
+    const queryClient = useQueryClient();
+    const chainQueryId = queries.ghostChain(initialModel, chain);
+    const ghostId = getGhostId(chainQueryId);
+    const context = {
+        queryKey: queries.model(initialModel),
+        ghostId,
+    };
+    const value = chain.reduce((model, item) => useGhostChainItem(model, item, options, context), initialModel);
+    const invalidate = () => {
+        invalidateGhosts(queryClient, initialModel, chain);
+    };
+    return {
+        value,
+        invalidate,
+    };
+};

package/dist/types/RenderComponent.d.ts

@@ -0,0 +1,6 @@
+import { type FC } from "react";
+interface Props {
+    render: () => unknown;
+}
+export declare const RenderComponent: FC<Props>;
+export {};

package/dist/types/context.d.ts

@@ -0,0 +1,6 @@
+export interface GhostFnContext {
+    ghostId?: string;
+    [key: string]: unknown;
+}
+export declare const ghostFnContext: import("context").CtxCascadeApi<GhostFnContext>;
+export declare const getGhostId: () => string | undefined;

package/dist/types/hash.d.ts

@@ -0,0 +1 @@
+export declare const hashObject: (model: object) => number;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { makeGhost } from "./makeGhost";
+export { type ReactGhost, UseGhostReturn } from "./types";
+export { getGhostId } from "./context";
+export { invalidateGhostsById } from "./invalidate";
+export { registerModelIdentifier } from "./modelIdentifier";
+export * from "./maybeGhost";

package/dist/types/invalidate.d.ts

@@ -0,0 +1,4 @@
+import { type QueryClient } from "@tanstack/react-query";
+import type { GhostChain } from "./types";
+export declare const invalidateGhostsById: (queryClient: QueryClient, ghostId: string) => void;
+export declare function invalidateGhosts(queryClient: QueryClient, model: unknown, chain: GhostChain): void;

package/dist/types/makeGhost.d.ts

@@ -0,0 +1,2 @@
+import { type ReactGhost } from "./types";
+export declare function makeGhost<T>(model: T): ReactGhost<T>;

package/dist/types/makeGhost.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/makeGhost.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/maybeGhost/asGhost.d.ts

@@ -0,0 +1,4 @@
+import { type ReactGhost } from "../types";
+import type { MaybeReactGhost, PropsWithFixedUpReactGhosts, PropsWithMaybeReactGhosts } from "./types";
+export declare function asGhost<T>(maybeGhost: MaybeReactGhost<T>): ReactGhost<T>;
+export declare function asGhostProps<T, TProps extends (keyof T)[] = (keyof T)[]>(props: PropsWithMaybeReactGhosts<T, TProps>, keys?: TProps): PropsWithFixedUpReactGhosts<T, TProps>;

package/dist/types/maybeGhost/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./asGhost";
+export * from "./types";

package/dist/types/maybeGhost/types.d.ts

@@ -0,0 +1,11 @@
+import { type OrOptional, type ReactGhost } from "../types";
+export type MaybeReactGhost<T> = T extends ReactGhost<infer U> ? ReactGhost<U> | U : T | ReactGhost<T>;
+export type PropsWithMaybeReactGhosts<T, TProps extends (keyof T)[]> = {
+    [K in keyof T]: K extends TProps[number] ? MaybeReactGhost<T[K] | OrOptional<T[K]>> : T[K] | OrOptional<T[K]>;
+};
+type FixedUpReactGhost<T> = T extends MaybeReactGhost<infer U> ? ReactGhost<U> : T;
+type WithGhostSuffix<T, TProps extends unknown[]> = T extends TProps[number] ? `${string & T}Ghost` : T;
+export type PropsWithFixedUpReactGhosts<T, TProps extends (keyof T)[]> = {
+    [K in keyof T as WithGhostSuffix<K, TProps>]: K extends TProps[number] ? FixedUpReactGhost<NonNullable<T[K]>> : T[K];
+};
+export {};

package/dist/types/maybeGhost/types.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modelIdentifier.d.ts

@@ -0,0 +1,3 @@
+import type { ModelIdentifier } from "./types";
+export declare const modelIdentifiers: ModelIdentifier[];
+export declare const registerModelIdentifier: (identifier: ModelIdentifier) => void;

package/dist/types/queries.d.ts

@@ -0,0 +1,10 @@
+import type { GhostChain, GhostChainItem, QueryKey } from "./types";
+export declare const getObjectQueryKey: (something: unknown) => string;
+export declare const ghostmakerQueryKey = "react-ghostmaker";
+export declare const getGhostId: (queryKey: QueryKey) => string;
+export declare const queries: {
+    ghostmaker: () => string[];
+    model: (model: unknown) => string[];
+    chainItem: (chainItem: GhostChainItem) => string[];
+    ghostChain: (model: unknown, chain: GhostChain) => string[];
+};

package/dist/types/resolveGhostChain.d.ts

@@ -0,0 +1,2 @@
+import { type GhostChain, type ExplicitAny } from "./types";
+export declare const resolveGhostChain: (initialModel: ExplicitAny, stack: GhostChain) => Promise<any>;

package/dist/types/testMocks.d.ts

@@ -0,0 +1,43 @@
+export declare let customerMocks: {
+    getName: () => void;
+    getDetailed: (id: string) => CustomerDetailed;
+};
+export declare let projectMocks: {
+    getDetailed: (id: string) => ProjectDetailed;
+    findDetailed: (id: string) => ProjectDetailed | undefined;
+    getName: () => void;
+    getStatus: () => void;
+};
+export declare const getCustomerNameGhostIds: {
+    current?: string | undefined;
+};
+export declare class CustomerDetailed {
+    readonly id: string;
+    readonly name: string;
+    constructor(id: string, name: string);
+    getName(): string;
+}
+export declare class Customer {
+    readonly id: string;
+    constructor(id: string);
+    static ofId(id: string): Customer;
+    getDetailed(): Promise<CustomerDetailed>;
+    static get(id: string): Promise<CustomerDetailed>;
+}
+export declare class Project {
+    readonly id: string;
+    constructor(id: string);
+    static ofId(id: string): Project;
+    getDetailed(): Promise<ProjectDetailed>;
+    findDetailed(): Promise<ProjectDetailed | undefined>;
+}
+export declare class ProjectDetailed {
+    readonly id: string;
+    readonly name: string;
+    readonly customer: Customer;
+    constructor(id: string, name: string, customerId: string);
+    getName(): string;
+    getStatus(): Promise<string>;
+}
+export declare const ProjectGhost: import("./types").ReactGhost<typeof Project>;
+export declare const CustomerGhost: import("./types").ReactGhost<typeof Customer>;

package/dist/types/types.d.ts

@@ -0,0 +1,40 @@
+import { type QueryClient, type UseQueryOptions } from "@tanstack/react-query";
+import type { DependencyList, ReactNode } from "react";
+import type { Class, UnknownRecord } from "type-fest";
+export type ExplicitAny = any;
+export type OrOptional<T> = T extends undefined ? undefined : never;
+export type AnyFunction = (...args: ExplicitAny[]) => ExplicitAny;
+export interface UseQueryReturnType<T> {
+    result: T;
+}
+export type useGhostOptions<T = unknown> = Omit<UseQueryOptions<UseQueryReturnType<T>>, "queryKey" | "queryFn">;
+export interface ReactGhostMethods<T> extends Promise<T> {
+    useGhost: (options?: useGhostOptions) => UseGhostReturn<T>;
+    use: (options?: useGhostOptions) => T;
+    render: (transform?: (item: T) => ReactNode) => ReactNode;
+    transform: <U, U2 = U>(fn: (item: T extends ReactGhost<infer T2> ? T2 : T) => U2, dependencies?: DependencyList) => ReactGhost<U2>;
+    invalidate: (queryClient: QueryClient) => void;
+}
+export declare const transformFnProp: "___transformFn";
+export declare const isGhostMarker: "___ghostMarker";
+export type ReactGhost<T> = ReactGhostMethods<T> & {
+    [K in keyof NonNullable<T>]-?: NonNullable<T>[K] extends AnyFunction ? <TParams extends Parameters<NonNullable<T>[K]>>(...args: TParams) => ReactGhost<Awaited<ReturnType<NonNullable<T>[K]>> | OrOptional<T>> : ReactGhost<NonNullable<T>[K] | OrOptional<T>>;
+};
+export interface GhostChainItem {
+    propName: string | typeof transformFnProp;
+    args?: ExplicitAny[];
+}
+export type GhostChain = GhostChainItem[];
+export type GhostChainModelType = UnknownRecord | Class<unknown> | null | undefined;
+export type QueryKey = string[];
+export type InvalidateGhostFn = () => void;
+export interface GhostChainContext {
+    queryKey: QueryKey;
+    ghostId: string;
+}
+export interface UseGhostReturn<T> {
+    value: T;
+    invalidate: InvalidateGhostFn;
+}
+export declare function isReactGhost<T>(something: unknown): something is ReactGhost<T>;
+export type ModelIdentifier = (model: unknown) => string | undefined;

package/dist/types/useGhostChain.d.ts

@@ -0,0 +1,2 @@
+import { type GhostChain, type useGhostOptions, type UseGhostReturn } from "./types";
+export declare const useGhostChain: <T>(initialModel: unknown, chain: GhostChain, options?: useGhostOptions) => UseGhostReturn<T>;

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@mittwald/react-ghostmaker",
+  "version": "1.0.0",
+  "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
+  "contributors": [
+    "Marco Falkenberg <m.falkenberg@mittwald.de>"
+  ],
+  "type": "module",
+  "description": "Transform your async models into React Suspense-ready ghosts",
+  "keywords": [
+    "async",
+    "domain",
+    "lazy",
+    "load",
+    "model",
+    "query",
+    "react",
+    "react-suspense",
+    "suspense",
+    "tanstack"
+  ],
+  "homepage": "https://github.com/mittwald/react-ghostmaker#readme",
+  "repository": "github:mittwald/react-ghostmaker",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@sindresorhus/is": "^7.1.0",
+    "context": "^3.0.33",
+    "object-code": "^1.3.4",
+    "type-fest": "^5.1.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.37.0",
+    "@tanstack/react-query": "^5.90.5",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@typescript-eslint/eslint-plugin": "^8.46.1",
+    "@typescript-eslint/parser": "^8.46.1",
+    "eslint": "^9.37.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-json": "^4.0.1",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^16.4.0",
+    "happy-dom": "^20.0.2",
+    "license-checker-rseidelsohn": "^4.4.2",
+    "prettier": "^3.6.2",
+    "prettier-plugin-jsdoc": "^1.3.3",
+    "prettier-plugin-pkgsort": "^0.2.1",
+    "prettier-plugin-sort-json": "^4.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5",
+    "react": ">=19.2"
+  },
+  "scripts": {
+    "build": "pnpm build:clean && pnpm tsc",
+    "build:clean": "rimraf dist",
+    "format": "prettier --write '**/*.{ts,tsx,yaml,yml,json,md,mdx}'",
+    "license-check": "license-checker-rseidelsohn $*",
+    "test": "pnpm test:tsc && pnpm test:lint && pnpm test:build && pnpm test:vitest && pnpm test:licenses",
+    "test:build": "pnpm build",
+    "test:licenses": "pnpm license-check --unknown --failOn 'UNLICENSED;UNKNOWN'",
+    "test:lint": "eslint . --cache",
+    "test:tsc": "tsc --noEmit",
+    "test:vitest": "vitest run"
+  }
+}