👻 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
• 🚀 Quick Start
• 🎭 Basic Usage
• 🎨 Advanced Features
• 🔄 Error Handling & Loading States
• 🏗️ Working with Domain Models
• 🎭 Flexible Component Props with MaybeReactGhost
• 🔧 Cache Management
• 📚 Complete Example
• 🔍 API Reference
• 🤝 Requirements
• 📄 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

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:

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:

// ❌ 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:

// ✅ 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

// ✅ 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.

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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

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:

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:

// 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:

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:

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:

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:

// 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

---

Ready to make your async operations disappear like ghosts? 👻 Transform your React app with suspense-ready domain models today!