@mittwald/react-ghostmaker 1.4.2 → 1.5.0-alpha.1

package/dist/esm/makeGhost.test.js

@@ -181,7 +181,7 @@ describe("Hooks", () => {
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
             expect(customerMocks.getName).toHaveBeenCalledTimes(1);
             result.current?.invalidate();
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(100000);
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getName).toHaveBeenCalledTimes(2);
@@ -196,7 +196,7 @@ describe("Hooks", () => {
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
             expect(customerMocks.getName).toHaveBeenCalledTimes(1);
             ghost.invalidate(queryClient);
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(10000);
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getName).toHaveBeenCalledTimes(2);
@@ -211,7 +211,7 @@ describe("Hooks", () => {
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
             expect(customerMocks.getName).toHaveBeenCalledTimes(1);
             invalidateGhosts(queryClient, getCustomerNameGhostIds.current.queryKey);
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(10000);
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getName).toHaveBeenCalledTimes(2);
@@ -223,7 +223,7 @@ describe("Hooks", () => {
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(1);
             ghost.invalidate(queryClient);
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(10000);
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(2);
         });
@@ -234,7 +234,7 @@ describe("Hooks", () => {
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(1);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
             specialGhost.invalidate(queryClient);
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(10000);
             expect(projectMocks.getDetailed).toHaveBeenCalledTimes(2);
             expect(customerMocks.getDetailed).toHaveBeenCalledTimes(0);
         });
@@ -246,7 +246,7 @@ describe("Hooks", () => {
                 .fn()
                 .mockImplementation((id) => new ProjectDetailed(id, `CHANGED! Project ${id}`, "C1"));
             projectGhost.invalidate(queryClient);
-            await vitest.runOnlyPendingTimersAsync();
+            await vitest.advanceTimersByTimeAsync(10000);
             expect(projectMocks.getName).toHaveBeenCalledTimes(2);
         });
     });

package/dist/esm/resolveGhostChain.js

@@ -1,5 +1,6 @@
 import is, { assert } from "@sindresorhus/is";
 import { isReactGhost, transformFnProp, } from "./types";
+import { getQueryContext, ghostFnContext } from "./context";
 const resolveGhostChainItem = async (target, item) => {
     const { propName, args } = item;
     if (propName === transformFnProp) {
@@ -21,13 +22,19 @@ const resolveGhostChainItem = async (target, item) => {
         return property;
     }
     assert.function(property);
-    const asyncFn = property.bind(target);
-    return await asyncFn(...args);
+    return property.call(target, ...args);
 };
 export const resolveGhostChain = async (target, stack) => {
     let result = target;
+    const queryContext = getQueryContext();
     for (const item of stack) {
-        result = await resolveGhostChainItem(result, item);
+        if (queryContext) {
+            const resolveGhostChainItemWithContext = ghostFnContext.bind({ query: queryContext }, resolveGhostChainItem);
+            result = await resolveGhostChainItemWithContext(result, item);
+        }
+        else {
+            result = await resolveGhostChainItem(result, item);
+        }
     }
     return result;
 };

package/dist/esm/useGhostChain.js

@@ -1,67 +1,39 @@
-import is, { assert } from "@sindresorhus/is";
-import { useEffect, useEffectEvent, useMemo, useRef } from "react";
-import { transformFnProp, } from "./types";
+import is from "@sindresorhus/is";
+import { useEffect, useEffectEvent, useRef } from "react";
 import { useQueryClient, useSuspenseQuery } from "@tanstack/react-query";
 import { queries } from "./queries";
 import { ghostFnContext } from "./context";
-import { invalidateGhosts } from "./invalidate";
 import { hashObject } from "./hash";
+import { resolveGhostChain } from "./resolveGhostChain";
 export const useGhostChain = (target, chain, options) => {
     const queryClient = useQueryClient();
-    const context = {
-        queryKey: queries.target(target),
-    };
-    const value = chain.reduce((currentTarget, item) => useGhostChainItem(currentTarget, item, options, context), target);
-    const invalidate = () => invalidateGhosts(queryClient, queries.ghostChain(target, chain));
-    return {
-        value,
-        invalidate,
-    };
-};
-const useGhostChainItem = (target, item, options = {}, context) => {
-    const { propName, args } = item;
-    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(target), [target, ...transformDependencies]);
-    }
-    if (is.nullOrUndefined(target)) {
-        return target;
-    }
-    assert.object(target);
-    const targetPropertyName = propName;
-    const targetProperty = target[targetPropertyName];
-    context.queryKey = queries.chainItem(context.queryKey, item);
-    if (args === undefined) {
-        // no function call, just a property access
-        return targetProperty;
-    }
-    assert.function(targetProperty);
-    const targetFn = targetProperty.bind(target);
-    const queryKey = [...context.queryKey];
-    const query = useSuspenseQuery({
+    const queryKey = queries.ghostChain(target, chain);
+    const fn = () => resolveGhostChain(target, chain);
+    const queryResult = useSuspenseQuery({
         ...options,
-        queryKey,
         queryFn: async (ctx) => {
-            const targetFnWithContext = ghostFnContext.bind({ query: ctx }, targetFn);
-            return { result: await targetFnWithContext(...args) };
+            const targetFnWithContext = ghostFnContext.bind({ query: ctx }, fn);
+            return { result: await targetFnWithContext() };
         },
+        queryKey,
     });
-    useTargetAutoInvalidate(target, queryKey);
-    if (query.error) {
-        throw query.error;
+    if (queryResult.error) {
+        throw queryResult.error;
     }
-    return query.data.result;
+    useTargetAutoInvalidate(target, queryKey);
+    return {
+        value: queryResult.data.result,
+        invalidate: () => queryClient.invalidateQueries({
+            queryKey,
+        }),
+    };
 };
 const useTargetAutoInvalidate = (target, queryKey) => {
     const queryClient = useQueryClient();
     const invalidate = () => queryClient.invalidateQueries({
         queryKey,
     });
-    const targetHash = hashObject(target);
+    const targetHash = is.object(target) ? hashObject(target) : target;
     const prevTargetHash = useRef(targetHash);
     const joinedQueryKey = queryKey.join(".");
     const prevQueryId = useRef(joinedQueryKey);

package/dist/types/queries.d.ts

@@ -4,6 +4,6 @@ export declare const getModelId: (something: unknown) => string | undefined;
 export declare const queries: {
     ghostmaker: () => string[];
     target: (target: unknown) => string[];
-    chainItem: (prev: QueryKey, chainItem: GhostChainItem) => unknown[];
-    ghostChain: (target: unknown, chain: GhostChain) => unknown[];
+    chainItem: (prev: QueryKey, chainItem: GhostChainItem) => QueryKey;
+    ghostChain: (target: unknown, chain: GhostChain) => QueryKey;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/react-ghostmaker",
-  "version": "1.4.2",
+  "version": "1.5.0-alpha.1",
   "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
   "contributors": [
     "Marco Falkenberg <m.falkenberg@mittwald.de>"

package/README.md

@@ -1,871 +0,0 @@
-# 👻 React Ghost Maker
-
-Transform your async models into React Suspense-ready ghosts
-
-React Ghost Maker creates intelligent proxy objects (ghosts) from your domain
-models that seamlessly integrate with React Suspense and TanStack Query. These
-ghosts automatically handle async operations, caching, and loading states,
-making your code cleaner and more declarative.
-
-## 📖 Table of Contents
-
-- [✨ Features](#-features)
-- [🚀 Quick Start](#-quick-start)
-- [🎭 Basic Usage](#-basic-usage)
-- [🎨 Advanced Features](#-advanced-features)
-- [🔄 Error Handling & Loading States](#-error-handling--loading-states)
-- [🏗️ Working with Domain Models](#️-working-with-domain-models)
-- [🎭 Flexible Component Props with MaybeReactGhost](#-flexible-component-props-with-maybereactghost)
-- [🔧 Cache Management](#-cache-management)
-- [📚 Complete Example](#-complete-example)
-- [🔍 API Reference](#-api-reference)
-- [🤝 Requirements](#-requirements)
-- [📄 License](#-license)
-
-## ✨ Features
-
-🎭 **Ghost Proxies**: Transform any object—models, existing API clients,
-services, or utilities into a suspense-ready ghost
-
-- ⚡ **Lazy Execution**: Ghosts don't execute until `.use()` or `.render()` is
-  called
-- 🎯 **Precise Loading States**: Control exactly where Suspense boundaries
-  trigger
-- 🔄 **TanStack Query Integration**: Built-in caching and query management
-- 🔑 **No Query Key Management**: Automatic query key generation - no manual key
-  handling required
-- 🛡️ **Type Safe**: Full TypeScript support with preserved method signatures
-- 🔗 **Method Chaining**: Chain async method calls naturally
-- 🎨 **Transform & Render**: Transform data and render components seamlessly
-- 📦 **Minimal Dependencies**: Only peer dependencies on React and TanStack
-  Query
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-npm install @mittwald/react-ghostmaker @tanstack/react-query
-# or
-pnpm add @mittwald/react-ghostmaker @tanstack/react-query
-```
-
-### Setup
-
-Wrap your app with TanStack Query's `QueryClientProvider`:
-
-```tsx
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import App from "./App";
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-    },
-  },
-});
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <App />
-    </QueryClientProvider>
-  </StrictMode>,
-);
-```
-
-### Why React Ghost Maker?
-
-**No More Query Key Management!** 🎉
-
-With traditional TanStack Query, you need to manually manage query keys:
-
-```tsx
-// ❌ Traditional TanStack Query - Manual key management
-function BlogComponent({ blogId }: { blogId: string }) {
-  const { data: blog } = useQuery({
-    queryKey: ["blog", blogId],
-    queryFn: () => fetchBlog(blogId),
-  });
-
-  const { data: author } = useQuery({
-    queryKey: ["blog", blogId, "author"],
-    queryFn: () => fetchAuthor(blog.authorId),
-    enabled: !!blog,
-  });
-
-  // More queries = more key management complexity...
-}
-```
-
-With React Ghost Maker, query keys are handled automatically:
-
-```tsx
-// ✅ React Ghost Maker - Zero key management
-function BlogComponent({ blogId }: { blogId: string }) {
-  const blogGhost = BlogGhost.ofId(blogId);
-
-  // Automatic query keys based on method chains
-  const author = blogGhost.getDetailed().getAuthor().use();
-
-  // No keys to manage, no dependencies to track!
-}
-```
-
-**Lazy Execution & Precise Loading States!** ⚡
-
-Ghosts are completely lazy - they don't execute until you call `.use()` or
-`.render()`. This means you can:
-
-- **Define ghosts anywhere** in your application
-- **Pass them down** through component trees without triggering requests
-- **Control exactly where** Suspense boundaries trigger
-- **Create precise loading states** deep in your component hierarchy
-
-```tsx
-// ✅ Ghost creation is instant - no network request yet
-function App() {
-  const blogGhost = BlogGhost.ofId("123").getDetailed();
-
-  return (
-    <Layout>
-      <Sidebar />
-      <MainContent>
-        {/* Suspense only triggers HERE when data is actually needed */}
-        <Suspense fallback={<BlogSkeleton />}>
-          <BlogDetails blog={blogGhost} />
-        </Suspense>
-      </MainContent>
-    </Layout>
-  );
-}
-
-function BlogDetails({ blog }: { blog: ReactGhost<DetailedBlog> }) {
-  // Network request happens HERE, not in App component
-  const blogData = blog.use();
-
-  return <article>{blogData.title}</article>;
-}
-
-// vs. Traditional approach - immediate execution
-function TraditionalApp() {
-  // ❌ Query executes immediately, forces Suspense at top level
-  const { data: blog } = useQuery({
-    queryKey: ["blog", "123"],
-    queryFn: () => fetchBlog("123"),
-  });
-
-  // Must handle loading at this level
-  if (!blog) return <GlobalLoader />;
-
-  return <Layout>...</Layout>;
-}
-```
-
-## 🎭 Basic Usage
-
-### Creating Your First Ghost
-
-React Ghost Maker can turn any object into a ghost—not just domain models, but
-also existing API clients, service objects, or utility classes. This makes it
-easy to add Suspense and caching to legacy code or third-party libraries.
-
-```tsx
-import { makeGhost } from "@mittwald/react-ghostmaker";
-import { Suspense } from "react";
-
-// Example: Wrapping an API client
-class BlogApiClient {
-  async fetchBlog(id: string) {
-    const response = await fetch(`/api/blogs/${id}`);
-    return response.json();
-  }
-}
-
-const BlogApiGhost = makeGhost(new BlogApiClient());
-
-function BlogView() {
-  // Use ghostified API client
-  const blog = BlogApiGhost.fetchBlog("123").use();
-  return <article>{blog.title}</article>;
-}
-
-// ...existing code...
-
-// You can also use domain models as shown below:
-class Blog {
-  constructor(public id: string) {}
-  static ofId(id: string): Blog {
-    return new Blog(id);
-  }
-  async getDetailed() {
-    const response = await fetch(`/api/blogs/${this.id}`);
-    const data = await response.json();
-    return new DetailedBlog(data);
-  }
-}
-
-class DetailedBlog extends Blog {
-  constructor(data: { id: string; title: string; author: string }) {
-    super(data.id);
-    this.title = data.title;
-    this.author = data.author;
-  }
-  public readonly title: string;
-  public readonly author: string;
-}
-
-const BlogGhost = makeGhost(Blog);
-
-function BlogViewModel() {
-  const blogGhost = BlogGhost.ofId("123");
-  const { value: blogTitle, invalidate } = blogGhost
-    .getDetailed()
-    .title.transform((title) => title.toUpperCase())
-    .useGhost();
-  return (
-    <article>
-      <h2>{blogTitle}</h2>
-      <button onClick={invalidate}>Refresh</button>
-    </article>
-  );
-}
-
-// Wrap with Suspense
-function App() {
-  return (
-    <Suspense fallback={<div>Loading blog...</div>}>
-      <BlogView />
-      <BlogViewModel />
-    </Suspense>
-  );
-}
-```
-
-### Method Chaining
-
-Ghosts support natural method chaining for complex async operations:
-
-```tsx
-class BlogService {
-  async getBlog(id: string) {
-    return new Blog(id);
-  }
-}
-
-class Blog {
-  constructor(public id: string) {}
-
-  async getAuthor() {
-    const response = await fetch(`/api/blogs/${this.id}/author`);
-    return new Author(await response.json());
-  }
-}
-
-class Author {
-  constructor(public data: any) {}
-
-  async getProfile() {
-    const response = await fetch(`/api/authors/${this.data.id}/profile`);
-    return response.json();
-  }
-}
-
-const BlogServiceGhost = makeGhost(new BlogService());
-
-function BlogAuthorProfile() {
-  // Chain multiple async operations seamlessly
-  const authorProfile = BlogServiceGhost.getBlog("123")
-    .getAuthor()
-    .getProfile()
-    .use();
-
-  return <div>{authorProfile.bio}</div>;
-}
-```
-
-## 🎨 Advanced Features
-
-### Transform Data
-
-Transform your data before rendering:
-
-```tsx
-function BlogTitle() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  const title = blogGhost
-    .getDetailed()
-    .title.transform((title) => title.toUpperCase())
-    .use();
-
-  return <h1>{title}</h1>;
-}
-```
-
-### Render Method
-
-Use the `render` method for inline rendering:
-
-```tsx
-function BlogContent() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  return <div>{blogGhost.getDetailed().title.render()}</div>;
-}
-```
-
-### Custom Query Options
-
-Pass TanStack Query options for fine-grained control:
-
-```tsx
-function CachedBlogData() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  const blogData = blogGhost.getDetailed().use({
-    staleTime: 10 * 60 * 1000, // 10 minutes
-    retry: 3,
-    refetchOnWindowFocus: false,
-  });
-
-  return <div>{blogData.title}</div>;
-}
-```
-
-### Access Query State with useGhost
-
-Use `useGhost` for full query state access and invalidation:
-
-```tsx
-function BlogWithControls() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  const { value: blogData, invalidate } = blogGhost.getDetailed().useGhost({
-    staleTime: 5 * 60 * 1000,
-  });
-
-  return (
-    <div>
-      <h1>{blogData.title}</h1>
-      <p>By: {blogData.author}</p>
-      <button onClick={invalidate}>Refresh Blog</button>
-    </div>
-  );
-}
-```
-
-### Direct Await Outside React
-
-You can directly await ghosts outside of React components for imperative
-operations:
-
-```tsx
-const BlogGhost = makeGhost(Blog);
-
-// Direct await for form submission
-async function handleBlogUpdate(blogId: string, updates: any) {
-  try {
-    const blogGhost = BlogGhost.ofId(blogId);
-    const blogData = await blogGhost.getDetailed();
-
-    await updateBlog(blogData.id, updates);
-
-    // Invalidate cache after update
-    invalidateGhostsById(`blog-${blogData.id}`);
-  } catch (error) {
-    console.error("Failed to update blog:", error);
-  }
-}
-
-// Use in event handlers
-function DeleteButton() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  const handleDelete = async () => {
-    if (confirm("Are you sure?")) {
-      const blog = await blogGhost;
-      await deleteBlog(blog.id);
-      invalidateGhostsById(`blog-${blog.id}`);
-    }
-  };
-
-  return <button onClick={handleDelete}>Delete Blog</button>;
-}
-```
-
-## 🔄 Error Handling & Loading States
-
-### Error Boundaries
-
-Handle errors with React Error Boundaries:
-
-```tsx
-import { ErrorBoundary } from "react-error-boundary";
-
-function ErrorFallback({ error, resetErrorBoundary }: any) {
-  return (
-    <div role="alert">
-      <h2>Something went wrong:</h2>
-      <pre>{error.message}</pre>
-      <button onClick={resetErrorBoundary}>Try again</button>
-    </div>
-  );
-}
-
-function App() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  return (
-    <ErrorBoundary FallbackComponent={ErrorFallback}>
-      <Suspense fallback={<div>Loading...</div>}>
-        <BlogView />
-      </Suspense>
-    </ErrorBoundary>
-  );
-}
-```
-
-### Nested Suspense Boundaries
-
-Create granular loading states with nested Suspense:
-
-```tsx
-function BlogPage() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  return (
-    <article>
-      <Suspense fallback={<div>Loading title...</div>}>
-        <BlogTitle ghost={blogGhost} />
-      </Suspense>
-
-      <Suspense fallback={<div>Loading content...</div>}>
-        <BlogContent ghost={blogGhost} />
-      </Suspense>
-
-      <Suspense fallback={<div>Loading author...</div>}>
-        <BlogAuthor ghost={blogGhost} />
-      </Suspense>
-    </article>
-  );
-}
-```
-
-
-## 🏗️ Working with Domain Models
-
-### Model Identification
-
-#### Using the `GhostMakerModel` Decorator (Recommended)
-
-You can now use the `GhostMakerModel` decorator to define model names and IDs for automatic query key generation. This is the recommended and most convenient way to ensure stable and meaningful cache keys for your models.
-
-```tsx
-import { GhostMakerModel } from "@mittwald/react-ghostmaker";
-
-@GhostMakerModel({
-  name: "User",
-  getId: (user) => user.id,
-})
-class User {
-  constructor(
-    public id: string,
-    public name: string,
-  ) {}
-}
-
-@GhostMakerModel({
-  name: "Blog",
-  getId: (blog) => blog.id,
-})
-class Blog {
-  constructor(
-    public id: string,
-    public title: string,
-  ) {}
-}
-```
-
-**Advantages:**
-
-- Declarative, directly on the model class
-- No need for central registration
-- Name and ID can be set explicitly (for readable query keys)
-- Works for multiple models and inheritance
-
-#### Alternative: `registerModelIdentifier` (deprecated)
-
-The previous `registerModelIdentifier` function is still available but marked as deprecated. It can be used to centrally register IDs for models:
-
-```tsx
-import { registerModelIdentifier } from "@mittwald/react-ghostmaker";
-
-registerModelIdentifier((model) => {
-  if (model instanceof User) return `user-${model.id}`;
-  if (model instanceof Blog) return `blog-${model.id}`;
-  return undefined;
-});
-```
-
-> **Note:** Prefer the `GhostMakerModel` decorator for new projects.
-
-## 🎭 Flexible Component Props with MaybeReactGhost
-
-The `MaybeReactGhost` pattern allows your components to accept both ghost
-objects and regular objects, making them more flexible and reusable.
-
-### Basic Usage
-
-Use `MaybeReactGhost<T>` for component props that should work with both ghosts
-and regular objects:
-
-```tsx
-import { type MaybeReactGhost, asGhostProps } from "@mittwald/react-ghostmaker";
-
-interface Props {
-  blog: MaybeReactGhost<Blog>;
-}
-
-function BlogCard(props: Props) {
-  // Automatically handles both ghost and regular objects
-  const { blogGhost } = asGhostProps(props);
-
-  return (
-    <div>
-      {blogGhost.getDetailed().title.render()}
-    </div>
-  );
-}
-
-// Works with both ghosts and regular objects
-<BlogCard blog={BlogGhost.ofId("123")} />
-<BlogCard blog={new Blog("123")} />
-```
-
-### Advanced Patterns
-
-You can build more complex component hierarchies where data can be passed down
-either as resolved values or as ghosts:
-
-```tsx
-// This component can work with both resolved and unresolved blog data
-function BlogDisplay(props: { blog: MaybeReactGhost<Blog> }) {
-  const { blogGhost } = asGhostProps(props);
-
-  const { value: blogData, invalidate } = blogGhost.getDetailed().useGhost();
-
-  return (
-    <article>
-      <h1>{blogData.title}</h1>
-      <p>By: {blogData.author}</p>
-      <button onClick={invalidate}>Refresh</button>
-      {/* Pass down as props - can be either resolved or ghost */}
-      <BlogComments blog={blogGhost} />
-      <BlogSidebar blog={blogData} /> {/* Already resolved */}
-    </article>
-  );
-}
-
-function BlogComments(props: { blog: MaybeReactGhost<Blog> }) {
-  const { blogGhost } = asGhostProps(props);
-  const comments = blogGhost.getComments().use();
-
-  return (
-    <div>
-      {comments.map((comment) => (
-        <div key={comment.id}>{comment.text}</div>
-      ))}
-    </div>
-  );
-}
-
-function BlogSidebar(props: { blog: Blog }) {
-  // This component expects resolved data
-  return (
-    <aside>
-      <h3>About this blog</h3>
-      <p>Blog ID: {props.blog.id}</p>
-    </aside>
-  );
-}
-```
-
-### When to Use MaybeReactGhost
-
-Use `MaybeReactGhost<T>` when:
-
-- You want components that can work with both async (ghost) and sync (regular)
-  data
-- Building reusable components that might receive data in different loading
-  states
-- Creating component libraries that should be flexible about data sources
-- Passing data down component trees where some levels might resolve the data
-  early
-
-Don't use it when:
-
-- You always know the data will be a ghost (use `ReactGhost<T>` directly)
-- You always know the data will be resolved (use the plain type `T`)
-- Simple components that don't need this flexibility
-
-## 🔧 Cache Management
-
-### Invalidate Queries
-
-#### Using `useGhost` Hook
-
-The `useGhost` hook returns an `invalidate` function for refreshing specific
-ghost data:
-
-```tsx
-function BlogView() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  const { value: blogData, invalidate } = blogGhost.getDetailed().useGhost();
-
-  const handleRefresh = () => {
-    invalidate(); // Refreshes only this specific ghost chain
-  };
-
-  return (
-    <div>
-      <h1>{blogData.title}</h1>
-      <button onClick={handleRefresh}>Refresh Blog</button>
-    </div>
-  );
-}
-```
-
-#### Using Ghost's `invalidate` Method
-
-Each ghost has an `invalidate` method that requires a QueryClient:
-
-```tsx
-import { useQueryClient } from "@tanstack/react-query";
-
-function UpdateBlogButton() {
-  const blogGhost = BlogGhost.ofId("123");
-  const queryClient = useQueryClient();
-
-  const handleUpdate = async () => {
-    const blogData = await blogGhost.getDetailed();
-    await updateBlog(blogData.id, { title: "Updated Title" });
-
-    // Invalidate this specific ghost
-    blogGhost.invalidate(queryClient);
-  };
-
-  return <button onClick={handleUpdate}>Update Blog</button>;
-}
-```
-
-#### Global Invalidation by ID
-
-Use `invalidateGhostsById` for global cache invalidation:
-
-```tsx
-import { invalidateGhostsById } from "@mittwald/react-ghostmaker";
-
-async function deleteBlog(blogId: string) {
-  await fetch(`/api/blogs/${blogId}`, { method: "DELETE" });
-
-  // Invalidate all cached data for this blog
-  invalidateGhostsById(`blog-${blogId}`);
-}
-```
-
-## 📚 Complete Example
-
-Here's a comprehensive example showing a blog application:
-
-```tsx
-// models/Blog.ts
-export class Blog {
-  constructor(public id: string) {}
-
-  static ofId(id: string): Blog {
-    return new Blog(id);
-  }
-
-  async getDetailed() {
-    const response = await fetch(`/api/blogs/${this.id}`);
-    const data = await response.json();
-    return new DetailedBlog(data);
-  }
-}
-
-export class DetailedBlog extends Blog {
-  constructor(data: { id: string; title: string; author: string }) {
-    super(data.id);
-    this.title = data.title;
-    this.author = data.author;
-  }
-
-  public readonly title: string;
-  public readonly author: string;
-
-  async getAuthor() {
-    const response = await fetch(`/api/authors/${this.author}`);
-    return response.json();
-  }
-}
-
-// models/react/BlogGhost.ts
-import { makeGhost, type ReactGhost } from "@mittwald/react-ghostmaker";
-import { Blog } from "../Blog";
-
-export const BlogGhost = makeGhost(Blog);
-export type BlogGhostType = ReactGhost<Blog>;
-
-// models/react/init.ts
-import { registerModelIdentifier } from "@mittwald/react-ghostmaker";
-import { Blog, DetailedBlog } from "../Blog";
-
-registerModelIdentifier((model) => {
-  if (model instanceof Blog) return `blog-${model.id}`;
-  if (model instanceof DetailedBlog) return `detailed-blog-${model.id}`;
-  return undefined;
-});
-
-// components/BlogPage.tsx
-import { Suspense } from "react";
-import { type ReactGhost } from "@mittwald/react-ghostmaker";
-import { Blog } from "../models/Blog";
-
-function BlogPage() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  return (
-    <article>
-      <Suspense fallback={<div>Loading title...</div>}>
-        <BlogTitle ghost={blogGhost} />
-      </Suspense>
-
-      <Suspense fallback={<div>Loading author...</div>}>
-        <BlogAuthor ghost={blogGhost} />
-      </Suspense>
-    </article>
-  );
-}
-
-function BlogTitle(props: { ghost: ReactGhost<Blog> }) {
-  const { value: title, invalidate } = props.ghost
-    .getDetailed()
-    .title.transform((t) => t.charAt(0).toUpperCase() + t.slice(1))
-    .useGhost();
-
-  return (
-    <div>
-      <h1>{title}</h1>
-      <button onClick={invalidate}>Refresh Title</button>
-    </div>
-  );
-}
-
-function BlogAuthor(props: { ghost: ReactGhost<Blog> }) {
-  const author = props.ghost.getDetailed().getAuthor().use();
-
-  return (
-    <div>
-      <h3>By: {author.name}</h3>
-      <p>{author.bio}</p>
-    </div>
-  );
-}
-
-// App.tsx
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { ErrorBoundary } from "react-error-boundary";
-import BlogPage from "./components/BlogPage";
-import { BlogGhost } from "./models/react/BlogGhost";
-import "./models/react/init"; // Initialize model identifiers
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      retry: 2,
-    },
-  },
-});
-
-function ErrorFallback({ error, resetErrorBoundary }: any) {
-  return (
-    <div>
-      <h2>Oops! Something went wrong</h2>
-      <p>{error.message}</p>
-      <button onClick={resetErrorBoundary}>Try Again</button>
-    </div>
-  );
-}
-
-export default function App() {
-  const blogGhost = BlogGhost.ofId("123");
-
-  return (
-    <QueryClientProvider client={queryClient}>
-      <ErrorBoundary FallbackComponent={ErrorFallback}>
-        <BlogPage />
-      </ErrorBoundary>
-    </QueryClientProvider>
-  );
-}
-```
-
-## 🔍 API Reference
-
-### `makeGhost<T>(model: T): ReactGhost<T>`
-
-Creates a ghost proxy from any object or class instance.
-
-**Key Benefits:**
-
-- 🔑 **Automatic Query Keys**: Generated based on method chains and model
-  identifiers
-- 🔄 **Smart Caching**: Each method call in a chain creates a unique,
-  deterministic cache key
-- 🎯 **Type Safety**: Preserves all original method signatures and return types
-
-### Ghost Methods
-
-- **`.use(options?)`** - Suspends until data is available, returns the resolved
-  value
-- **`.useGhost(options?)`** - Returns `{ value, invalidate }` with full query
-  control
-- **`.render(transform?)`** - Renders the value directly as a React element
-- **`.transform(fn, deps?)`** - Transforms the resolved value
-- **`.invalidate(queryClient)`** - Invalidate this specific ghost's cached data
-- **`await ghost`** - Directly await the ghost to get the resolved value
-
-
-### Utility Functions
-
-- **`asGhostProps(props)`** - Converts props to ghost-compatible format
-- **`GhostMakerModel(options)`** - Decorator to define model name and ID for automatic query key generation
-- **`invalidateGhostsById(id)`** - Globally invalidate cached data by ID
-- **`getGhostId(ghost)`** - Get the unique ID of a ghost
-
-### Types
-
-- **`MaybeReactGhost<T>`** - Type for props that accept both ghosts and regular objects
-- **`ReactGhost<T>`** - Type for ghost proxy objects
-- **`UseGhostReturn<T>`** - Return type of `useGhost()` with `{ value, invalidate }`
-
-## 🤝 Requirements
-
-- React >=19.2
-- TanStack Query ^5
-- TypeScript (recommended)
-
-## 📄 License
-
-MIT © [Mittwald CM Service GmbH & Co. KG](https://github.com/mittwald)
-
----
-
-**Ready to make your async operations disappear like ghosts? 👻** Transform your
-React app with suspense-ready domain models today!