@mittwald/react-ghostmaker 1.1.0 → 1.2.0

package/README.md

@@ -455,15 +455,22 @@ function BlogPage() {
 }
 ```
 
+
 ## 🏗️ Working with Domain Models
 
 ### Model Identification
 
-Register model identifiers for better caching:
+#### 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 { registerModelIdentifier } from "@mittwald/react-ghostmaker";
+import { GhostMakerModel } from "@mittwald/react-ghostmaker";
 
+@GhostMakerModel({
+  name: "User",
+  getId: (user) => user.id,
+})
 class User {
   constructor(
     public id: string,
@@ -471,14 +478,32 @@ class User {
   ) {}
 }
 
+@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";
 
-// Register identifiers for automatic cache key generation
 registerModelIdentifier((model) => {
   if (model instanceof User) return `user-${model.id}`;
   if (model instanceof Blog) return `blog-${model.id}`;
@@ -486,6 +511,8 @@ registerModelIdentifier((model) => {
 });
 ```
 
+> **Note:** Prefer the `GhostMakerModel` decorator for new projects.
+
 ## 🎭 Flexible Component Props with MaybeReactGhost
 
 The `MaybeReactGhost` pattern allows your components to accept both ghost

package/dist/esm/context.js

@@ -2,3 +2,8 @@ import { createCascade } from "context";
 export const ghostFnContext = createCascade();
 const useGhostFnContext = () => ghostFnContext.use();
 export const getQueryContext = () => useGhostFnContext()?.query;
+export function forwardQueryContext(fn) {
+    const queryContext = getQueryContext();
+    ghostFnContext.bind({ query: queryContext }, fn);
+    return fn();
+}

package/dist/esm/index.js

@@ -1,5 +1,6 @@
 export { makeGhost } from "./makeGhost";
-export { getQueryContext } from "./context";
+export { getQueryContext, forwardQueryContext } from "./context";
 export { invalidateGhosts } from "./invalidate";
-export { registerModelIdentifier } from "./modelIdentifier";
 export * from "./maybeGhost";
+export { GhostMakerModel } from "./metaData";
+export { getModelId, getModelName } from "./queries";

package/dist/esm/metaData.js

@@ -0,0 +1,9 @@
+const store = new Map();
+export const getMetaData = (something) => {
+    return store.get(something);
+};
+export function GhostMakerModel(options) {
+    return function (target) {
+        store.set(target, options);
+    };
+}

package/dist/esm/modelIdentifier.js

@@ -1,4 +1,5 @@
 export const modelIdentifiers = [];
+/** @deprecated Use GhostMakerModel (decorator) instead */
 export const registerModelIdentifier = (identifier) => {
     modelIdentifiers.push(identifier);
 };

package/dist/esm/queries.js

@@ -1,10 +1,46 @@
 import is from "@sindresorhus/is";
-import { modelIdentifiers } from "./modelIdentifier";
 import { hashObject } from "./hash";
-const getObjectName = (something) => {
+import { getMetaData } from "./metaData";
+import { modelIdentifiers } from "./modelIdentifier";
+export const getModelName = (something) => {
+    const isObject = is.object(something);
+    const getModelNameRecursive = (
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    klass) => {
+        if (!klass) {
+            return;
+        }
+        return (getMetaData(klass)?.name ??
+            getModelNameRecursive(Object.getPrototypeOf(klass)));
+    };
+    const klass = isObject ? something.constructor : undefined;
+    return getModelNameRecursive(klass);
+};
+export const getModelId = (something) => {
     const isObject = is.object(something);
+    const getIdRecursive = (
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    klass) => {
+        if (!klass) {
+            return;
+        }
+        const getId = getMetaData(klass)?.getId;
+        if (getId) {
+            return getId(something);
+        }
+        return getIdRecursive(Object.getPrototypeOf(klass));
+    };
+    const klass = isObject ? something.constructor : undefined;
+    return getIdRecursive(klass);
+};
+const getObjectName = (something) => {
+    const modelName = getModelName(something);
+    if (modelName) {
+        return modelName;
+    }
     const isClass = is.class(something);
     const isFunction = is.function(something);
+    const isObject = is.object(something);
     return isFunction
         ? something.name
         : isClass || isObject
@@ -16,6 +52,10 @@ const getTargetQueryKey = (something) => {
         return String(something);
     }
     const objectName = getObjectName(something);
+    const id = getModelId(something);
+    if (id) {
+        return `${objectName}@${id}`;
+    }
     const thisModelIdentifiers = modelIdentifiers
         .map((fn) => fn(something))
         .filter(is.string)

package/dist/esm/testMocks.js

@@ -1,5 +1,40 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
 import { beforeEach, vitest } from "vitest";
-import { getQueryContext, makeGhost, registerModelIdentifier } from ".";
+import { getQueryContext, makeGhost } from ".";
+import { GhostMakerModel } from "./metaData";
 const sleep = () => new Promise((resolve) => setTimeout(resolve, 200));
 export const advanceSleepTimer = async (times = 1) => {
     for (let i = 0; i < times; i++) {
@@ -29,71 +64,145 @@ beforeEach(() => {
         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();
-        return customerMocks.getDetailed(id);
-    }
-}
-export class Project {
-    id;
-    constructor(id) {
-        this.id = id;
-    }
-    static ofId(id) {
-        return new Project(id);
-    }
-    async getDetailed() {
-        await sleep();
-        return projectMocks.getDetailed(this.id);
-    }
-    async findDetailed() {
-        await sleep();
-        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();
-        return "active";
-    }
-}
+let CustomerDetailed = (() => {
+    let _classDecorators = [GhostMakerModel({
+            getId: (customer) => customer.id,
+            name: "CustomerDetailed",
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var CustomerDetailed = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            CustomerDetailed = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        id;
+        name;
+        constructor(id, name) {
+            this.id = id;
+            this.name = name;
+        }
+        getName() {
+            customerMocks.getName();
+            return this.name;
+        }
+    };
+    return CustomerDetailed = _classThis;
+})();
+export { CustomerDetailed };
+let Customer = (() => {
+    let _classDecorators = [GhostMakerModel({
+            getId: (customer) => customer.id,
+            name: "Customer",
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var Customer = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            Customer = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        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();
+            return customerMocks.getDetailed(id);
+        }
+    };
+    return Customer = _classThis;
+})();
+export { Customer };
+let Project = (() => {
+    let _classDecorators = [GhostMakerModel({
+            getId: (project) => project.id,
+            name: "Project",
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var Project = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            Project = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        id;
+        constructor(id) {
+            this.id = id;
+        }
+        static ofId(id) {
+            return new Project(id);
+        }
+        async getDetailed() {
+            await sleep();
+            return projectMocks.getDetailed(this.id);
+        }
+        async findDetailed() {
+            await sleep();
+            return projectMocks.findDetailed(this.id);
+        }
+    };
+    return Project = _classThis;
+})();
+export { Project };
+let ProjectDetailed = (() => {
+    let _classDecorators = [GhostMakerModel({
+            getId: (project) => project.id,
+            name: "ProjectDetailed",
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var ProjectDetailed = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ProjectDetailed = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        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();
+            return "active";
+        }
+    };
+    return ProjectDetailed = _classThis;
+})();
+export { ProjectDetailed };
 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/types/context.d.ts

@@ -12,3 +12,4 @@ export declare const getQueryContext: () => {
     pageParam?: unknown;
     direction?: unknown;
 } | undefined;
+export declare function forwardQueryContext<T>(fn: () => T): T;

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export { makeGhost } from "./makeGhost";
 export { type ReactGhost, UseGhostReturn } from "./types";
-export { getQueryContext } from "./context";
+export { getQueryContext, forwardQueryContext } from "./context";
 export { invalidateGhosts } from "./invalidate";
-export { registerModelIdentifier } from "./modelIdentifier";
 export * from "./maybeGhost";
+export { GhostMakerModel } from "./metaData";
+export { getModelId, getModelName } from "./queries";

package/dist/types/metaData.d.ts

@@ -0,0 +1,8 @@
+import type { Class } from "type-fest";
+interface GhostMakerModelOptions<T extends Class<unknown>> {
+    getId?: (instance: InstanceType<T>) => string;
+    name?: string;
+}
+export declare const getMetaData: (something: unknown) => GhostMakerModelOptions<Class<unknown>> | undefined;
+export declare function GhostMakerModel<T extends Class<unknown>>(options: GhostMakerModelOptions<T>): (target: T) => void;
+export {};

package/dist/types/modelIdentifier.d.ts

@@ -1,3 +1,4 @@
 import type { ModelIdentifier } from "./types";
 export declare const modelIdentifiers: ModelIdentifier[];
+/** @deprecated Use GhostMakerModel (decorator) instead */
 export declare const registerModelIdentifier: (identifier: ModelIdentifier) => void;

package/dist/types/queries.d.ts

@@ -1,4 +1,6 @@
 import type { GhostChain, GhostChainItem, QueryKey } from "./types";
+export declare const getModelName: (something: unknown) => string | undefined;
+export declare const getModelId: (something: unknown) => string | undefined;
 export declare const queries: {
     ghostmaker: () => string[];
     target: (target: unknown) => string[];

package/package.json

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