@mantajs/core 0.1.6 → 0.2.0-beta.0

package/dist/query/index.d.ts

@@ -0,0 +1,181 @@
+export type { QueryConfig, QueryDefinition, QueryHandlerContext } from './define-query';
+export { defineQuery, QueryRegistry } from './define-query';
+export type { EntityAccessMap, EntityAccessRule, QueryGraphDefinition } from './define-query-graph';
+export { defineQueryGraph, getEntityFilter, isEntityAllowed } from './define-query-graph';
+export type { QueryGraphExtensionContext, QueryGraphExtensionDefinition, QueryGraphExtensionResolver, } from './extend-query-graph';
+export { extendQueryGraph } from './extend-query-graph';
+import type { InferEntity } from '../dml/infer';
+import type { ILoggerPort } from '../ports/logger';
+import type { IRelationalQueryPort } from '../ports/relational-query';
+import type { QueryGraphExtensionDefinition } from './extend-query-graph';
+/**
+ * Entity registry — augmented by .manta/types/types.ts codegen.
+ * Unlike MantaEntities (which extends Record<string, DmlEntity>),
+ * this interface starts empty so keyof produces a strict union.
+ */
+export interface EntityRegistry extends MantaGeneratedEntityRegistry {
+}
+/**
+ * Entity name type — derived from EntityRegistry.
+ * When codegen runs, EntityName becomes a union of module names (e.g. 'catalog' | 'inventory').
+ * Without codegen, falls back to string for compatibility.
+ */
+export type EntityName = keyof EntityRegistry extends never ? string : Extract<keyof EntityRegistry, string>;
+/**
+ * Inferred entity result type — resolves to the DML-inferred shape when codegen is available,
+ * falls back to Record<string, unknown> otherwise.
+ */
+export type InferEntityResult<E extends EntityName> = E extends keyof EntityRegistry ? InferEntity<EntityRegistry[E]> : Record<string, unknown>;
+/**
+ * Configuration for Query.graph().
+ */
+export interface GraphQueryConfig<E extends EntityName = EntityName> {
+    entity: E;
+    fields?: string[];
+    filters?: Record<string, unknown>;
+    sort?: Record<string, 'asc' | 'desc'>;
+    pagination?: {
+        limit?: number;
+        offset?: number;
+    };
+    relPagination?: RelationPagination;
+    withDeleted?: boolean;
+    dangerouslyUnboundedRelations?: boolean;
+    /** Full-text search query — searches across all searchable fields of the entity. */
+    q?: string;
+}
+/**
+ * Per-relation pagination configuration.
+ */
+export type RelationPagination = Record<string, {
+    limit?: number;
+    offset?: number;
+}>;
+/**
+ * Configuration for Query.index().
+ */
+export interface IndexQueryConfig {
+    entity: EntityName;
+    fields?: string[];
+    filters?: Record<string, unknown>;
+    sort?: Record<string, 'asc' | 'desc'>;
+    pagination?: {
+        limit?: number;
+        offset?: number;
+    };
+}
+/**
+ * Resolver function type — provided by modules to resolve entities.
+ */
+export type EntityResolver = (config: {
+    fields?: string[];
+    filters?: Record<string, unknown>;
+    sort?: Record<string, 'asc' | 'desc'>;
+    pagination?: {
+        limit?: number;
+        offset?: number;
+    };
+    withDeleted?: boolean;
+}) => Promise<Record<string, unknown>[]>;
+/**
+ * Query service — provides graph() and index() for cross-module data resolution.
+ *
+ * Modules register their entity resolvers. Query.graph() orchestrates joins
+ * across modules, applying pagination, filtering, and entity count protection.
+ */
+export declare class QueryService {
+    private _resolvers;
+    private _searchableFields;
+    private _indexModule;
+    private _relationalQuery;
+    private _maxTotalEntities;
+    private _beforeFetch;
+    /** Query graph extensions — modules that own external entities (PostHog, Stripe, etc.) */
+    private _extensions;
+    /** MantaApp reference — passed to extension resolvers. Set by bootstrap. */
+    private _app;
+    /** Logger — passed to extension resolvers. Set by bootstrap. */
+    private _logger;
+    constructor(options?: {
+        maxTotalEntities?: number;
+    });
+    /**
+     * Register a query graph extension — a module-level resolver for external entities.
+     * Called by the bootstrap once per discovered extension.
+     */
+    registerExtension(extension: QueryGraphExtensionDefinition): void;
+    /**
+     * Provide the MantaApp + logger to extension resolvers. Called by bootstrap.
+     */
+    setExtensionContext(app: any, logger: ILoggerPort): void;
+    /**
+     * Find the extension (if any) that owns the given normalized entity key.
+     */
+    private _findExtensionFor;
+    /**
+     * Validate that a query's filters are supported by an extension.
+     * Throws MantaError with a clear message if any filter is not supported.
+     */
+    private _validateExtensionFilters;
+    /**
+     * Normalize an entity name to canonical lookup key.
+     * Handles: 'CustomerGroup' → 'customergroup', 'customer_group' → 'customergroup', 'customerGroup' → 'customergroup'
+     * We strip all separators and lowercase for lookup so any format resolves.
+     */
+    private _normalizeKey;
+    /**
+     * Register an entity resolver for a module.
+     */
+    registerResolver(entityName: string, resolver: EntityResolver): void;
+    /**
+     * Register searchable fields for an entity (used for `q` parameter in graph queries).
+     */
+    registerSearchableFields(entityName: string, fields: string[]): void;
+    /**
+     * Get searchable fields for an entity.
+     */
+    getSearchableFields(entityName: string): string[];
+    /**
+     * Register a relational query port for native SQL JOINs.
+     * When registered, graph() delegates to this port for queries that include relations.
+     */
+    registerRelationalQuery(rq: IRelationalQueryPort): void;
+    /**
+     * Register the Index module for Query.index().
+     */
+    registerIndexModule(indexModule: {
+        query: (config: IndexQueryConfig) => Promise<Record<string, unknown>[]>;
+    }): void;
+    /**
+     * Set a beforeFetch hook for circuit breaker pattern.
+     */
+    set beforeFetch(fn: (module: string, query: unknown) => Promise<Record<string, unknown>[] | null>);
+    /**
+     * Query.graph() — resolve entities with cross-module joins.
+     *
+     * Default limit: 100. Hard limit: 10,000 entities (configurable).
+     * Throws INVALID_DATA if entity count exceeds limit.
+     */
+    graph<E extends EntityName>(config: GraphQueryConfig<E>): Promise<InferEntityResult<E>[]>;
+    /**
+     * Apply in-memory search filter on results using searchable fields.
+     * Filters rows where any searchable field contains the query string (case-insensitive).
+     */
+    private _applySearch;
+    /**
+     * Query.index() — denormalized read via Index module.
+     * Requires Index module loaded + entity indexed.
+     */
+    index(config: IndexQueryConfig): Promise<Record<string, unknown>[]>;
+    /**
+     * Query.graphAndCount() — like graph() but also returns total count for pagination.
+     * Delegates to IRelationalQueryPort.findAndCountWithRelations() when available.
+     */
+    graphAndCount<E extends EntityName>(config: GraphQueryConfig<E>): Promise<[InferEntityResult<E>[], number]>;
+    /**
+     * Query.gql() — REMOVED per spec. Throws NOT_IMPLEMENTED.
+     */
+    gql(): Promise<never>;
+    _reset(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"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"}

package/dist/query/index.js

@@ -0,0 +1,288 @@
+// SPEC-011 — Query system with graph() for cross-module joins
+// SPEC-V2 — defineQuery() for CQRS read side
+export { defineQuery, QueryRegistry } from './define-query';
+export { defineQueryGraph, getEntityFilter, isEntityAllowed } from './define-query-graph';
+export { extendQueryGraph } from './extend-query-graph';
+import { MantaError } from '../errors/manta-error';
+/**
+ * Query service — provides graph() and index() for cross-module data resolution.
+ *
+ * Modules register their entity resolvers. Query.graph() orchestrates joins
+ * across modules, applying pagination, filtering, and entity count protection.
+ */
+export class QueryService {
+    _resolvers = new Map();
+    _searchableFields = new Map();
+    _indexModule = null;
+    _relationalQuery = null;
+    _maxTotalEntities;
+    _beforeFetch = null;
+    /** Query graph extensions — modules that own external entities (PostHog, Stripe, etc.) */
+    _extensions = [];
+    /** MantaApp reference — passed to extension resolvers. Set by bootstrap. */
+    // biome-ignore lint/suspicious/noExplicitAny: avoid circular type dep
+    _app = null;
+    /** Logger — passed to extension resolvers. Set by bootstrap. */
+    _logger = null;
+    constructor(options) {
+        this._maxTotalEntities = options?.maxTotalEntities ?? 10000;
+    }
+    /**
+     * Register a query graph extension — a module-level resolver for external entities.
+     * Called by the bootstrap once per discovered extension.
+     */
+    registerExtension(extension) {
+        this._extensions.push(extension);
+    }
+    /**
+     * Provide the MantaApp + logger to extension resolvers. Called by bootstrap.
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: avoid circular type dep
+    setExtensionContext(app, logger) {
+        this._app = app;
+        this._logger = logger;
+    }
+    /**
+     * Find the extension (if any) that owns the given normalized entity key.
+     */
+    _findExtensionFor(entityKey) {
+        for (const ext of this._extensions) {
+            for (const owned of ext.owns) {
+                if (this._normalizeKey(owned) === entityKey)
+                    return ext;
+            }
+        }
+        return null;
+    }
+    /**
+     * Validate that a query's filters are supported by an extension.
+     * Throws MantaError with a clear message if any filter is not supported.
+     */
+    _validateExtensionFilters(ext, entity, filters) {
+        if (!filters || !ext.supportedFilters)
+            return;
+        const supported = ext.supportedFilters[entity];
+        if (!supported)
+            return;
+        const unsupported = Object.keys(filters).filter((k) => !supported.includes(k));
+        if (unsupported.length > 0) {
+            throw new MantaError('INVALID_DATA', `Entity "${entity}" does not support filter(s): ${unsupported.join(', ')}. Supported filters: ${supported.join(', ')}.`);
+        }
+    }
+    /**
+     * Normalize an entity name to canonical lookup key.
+     * Handles: 'CustomerGroup' → 'customergroup', 'customer_group' → 'customergroup', 'customerGroup' → 'customergroup'
+     * We strip all separators and lowercase for lookup so any format resolves.
+     */
+    _normalizeKey(name) {
+        return name.replace(/[_\s-]/g, '').toLowerCase();
+    }
+    /**
+     * Register an entity resolver for a module.
+     */
+    registerResolver(entityName, resolver) {
+        this._resolvers.set(this._normalizeKey(entityName), resolver);
+    }
+    /**
+     * Register searchable fields for an entity (used for `q` parameter in graph queries).
+     */
+    registerSearchableFields(entityName, fields) {
+        this._searchableFields.set(this._normalizeKey(entityName), fields);
+    }
+    /**
+     * Get searchable fields for an entity.
+     */
+    getSearchableFields(entityName) {
+        return this._searchableFields.get(this._normalizeKey(entityName)) ?? [];
+    }
+    /**
+     * Register a relational query port for native SQL JOINs.
+     * When registered, graph() delegates to this port for queries that include relations.
+     */
+    registerRelationalQuery(rq) {
+        this._relationalQuery = rq;
+    }
+    /**
+     * Register the Index module for Query.index().
+     */
+    registerIndexModule(indexModule) {
+        this._indexModule = indexModule;
+    }
+    /**
+     * Set a beforeFetch hook for circuit breaker pattern.
+     */
+    set beforeFetch(fn) {
+        this._beforeFetch = fn;
+    }
+    /**
+     * Query.graph() — resolve entities with cross-module joins.
+     *
+     * Default limit: 100. Hard limit: 10,000 entities (configurable).
+     * Throws INVALID_DATA if entity count exceeds limit.
+     */
+    async graph(config) {
+        const entityKey = this._normalizeKey(config.entity);
+        // Apply default pagination
+        const pagination = config.pagination ?? { limit: 100, offset: 0 };
+        // Check circuit breaker hook
+        if (this._beforeFetch) {
+            const cached = await this._beforeFetch(entityKey, config);
+            if (cached !== null)
+                return cached;
+        }
+        // Route to query graph extension if an external module owns this entity.
+        // External entities are resolved by their module's extendQueryGraph() resolver,
+        // not by Drizzle (they have no local table).
+        const extension = this._findExtensionFor(entityKey);
+        if (extension) {
+            this._validateExtensionFilters(extension, config.entity, config.filters);
+            const rows = await extension.resolve({ ...config, pagination }, { app: this._app, logger: this._logger ?? console });
+            // Entity count protection
+            if (!config.dangerouslyUnboundedRelations && rows.length > this._maxTotalEntities) {
+                throw new MantaError('INVALID_DATA', `Query returned ${rows.length} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+            }
+            return rows;
+        }
+        // Delegate to IRelationalQueryPort if available
+        // Always delegate when we have one — it handles alias resolution for relation fields
+        // (e.g. 'customers' → M:N relation via pivot table)
+        if (this._relationalQuery) {
+            const results = await this._relationalQuery.findWithRelations({
+                entity: config.entity,
+                fields: config.fields,
+                filters: config.filters,
+                sort: config.sort,
+                pagination,
+                relPagination: config.relPagination,
+                withDeleted: config.withDeleted,
+            });
+            // Entity count protection
+            if (!config.dangerouslyUnboundedRelations && results.length > this._maxTotalEntities) {
+                throw new MantaError('INVALID_DATA', `Query returned ${results.length} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+            }
+            return this._applySearch(results, config.q, entityKey);
+        }
+        // Fallback to legacy resolver path
+        const resolver = this._resolvers.get(entityKey);
+        if (!resolver) {
+            throw new MantaError('UNKNOWN_MODULES', `No resolver registered for entity "${config.entity}"`);
+        }
+        // Resolve root entities
+        const results = await resolver({
+            fields: config.fields,
+            filters: config.filters,
+            sort: config.sort,
+            pagination,
+            withDeleted: config.withDeleted,
+        });
+        // Apply in-memory search filter
+        const filtered = this._applySearch(results, config.q, entityKey);
+        // Entity count protection
+        const total = filtered.length;
+        if (!config.dangerouslyUnboundedRelations && total > this._maxTotalEntities) {
+            throw new MantaError('INVALID_DATA', `Query returned ${total} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+        }
+        return filtered;
+    }
+    /**
+     * Apply in-memory search filter on results using searchable fields.
+     * Filters rows where any searchable field contains the query string (case-insensitive).
+     */
+    _applySearch(results, q, entityKey) {
+        if (!q || !q.trim() || !entityKey)
+            return results;
+        const searchableFields = this._searchableFields.get(entityKey);
+        if (!searchableFields || searchableFields.length === 0)
+            return results;
+        const needle = q.trim().toLowerCase();
+        return results.filter((row) => searchableFields.some((field) => {
+            const value = row[field];
+            return value != null && String(value).toLowerCase().includes(needle);
+        }));
+    }
+    /**
+     * Query.index() — denormalized read via Index module.
+     * Requires Index module loaded + entity indexed.
+     */
+    async index(config) {
+        if (!this._indexModule) {
+            throw new MantaError('UNKNOWN_MODULES', 'Index module is not loaded. Use Query.graph() or enable the Index module.');
+        }
+        return this._indexModule.query(config);
+    }
+    /**
+     * Query.graphAndCount() — like graph() but also returns total count for pagination.
+     * Delegates to IRelationalQueryPort.findAndCountWithRelations() when available.
+     */
+    async graphAndCount(config) {
+        const entityKey = this._normalizeKey(config.entity);
+        // Apply default pagination
+        const pagination = config.pagination ?? { limit: 100, offset: 0 };
+        // Check circuit breaker hook
+        if (this._beforeFetch) {
+            const cached = await this._beforeFetch(entityKey, config);
+            if (cached !== null)
+                return [cached, cached.length];
+        }
+        // Route to query graph extension if an external module owns this entity.
+        const extension = this._findExtensionFor(entityKey);
+        if (extension) {
+            this._validateExtensionFilters(extension, config.entity, config.filters);
+            const rows = await extension.resolve({ ...config, pagination }, { app: this._app, logger: this._logger ?? console });
+            if (!config.dangerouslyUnboundedRelations && rows.length > this._maxTotalEntities) {
+                throw new MantaError('INVALID_DATA', `Query returned ${rows.length} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+            }
+            // External resolvers don't provide a separate count yet — return rows.length as approximation.
+            return [rows, rows.length];
+        }
+        if (this._relationalQuery) {
+            const [results, count] = await this._relationalQuery.findAndCountWithRelations({
+                entity: config.entity,
+                fields: config.fields,
+                filters: config.filters,
+                sort: config.sort,
+                pagination,
+                relPagination: config.relPagination,
+                withDeleted: config.withDeleted,
+            });
+            if (!config.dangerouslyUnboundedRelations && results.length > this._maxTotalEntities) {
+                throw new MantaError('INVALID_DATA', `Query returned ${results.length} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+            }
+            return [results, count];
+        }
+        // Fallback to legacy resolver path — no native count support
+        const resolver = this._resolvers.get(entityKey);
+        if (!resolver) {
+            throw new MantaError('UNKNOWN_MODULES', `No resolver registered for entity "${config.entity}"`);
+        }
+        const results = await resolver({
+            fields: config.fields,
+            filters: config.filters,
+            sort: config.sort,
+            pagination,
+            withDeleted: config.withDeleted,
+        });
+        if (!config.dangerouslyUnboundedRelations && results.length > this._maxTotalEntities) {
+            throw new MantaError('INVALID_DATA', `Query returned ${results.length} entities, exceeding maximum of ${this._maxTotalEntities}. Use pagination or reduce scope.`);
+        }
+        // Legacy resolvers don't provide count — return results.length as approximation
+        return [results, results.length];
+    }
+    /**
+     * Query.gql() — REMOVED per spec. Throws NOT_IMPLEMENTED.
+     */
+    async gql() {
+        throw new MantaError('NOT_IMPLEMENTED', 'Query.gql() has been removed. Use Query.graph() instead.');
+    }
+    _reset() {
+        this._resolvers.clear();
+        this._searchableFields.clear();
+        this._indexModule = null;
+        this._relationalQuery = null;
+        this._beforeFetch = null;
+        this._extensions = [];
+        this._app = null;
+        this._logger = null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"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"}

package/dist/service/define.d.ts

@@ -0,0 +1,97 @@
+import type { DmlEntity } from '../dml/entity';
+import type { InferEntity } from '../dml/infer';
+import type { ModelProxy, ModelRef } from '../link/index';
+import type { ILoggerPort } from '../ports/logger';
+import type { CursorPagination } from '../ports/types';
+/**
+ * Typed repository — wraps IRepository with entity-typed methods.
+ * Mutations (update, delete, create) are auto-snapshotted for compensation.
+ */
+export interface TypedRepository<T> {
+    find(options?: {
+        where?: Partial<T>;
+        withDeleted?: boolean;
+        limit?: number;
+        offset?: number;
+        order?: Partial<Record<keyof T & string, 'ASC' | 'DESC'>>;
+        cursor?: CursorPagination;
+    }): Promise<T[]>;
+    findAndCount(options?: {
+        where?: Partial<T>;
+        withDeleted?: boolean;
+        limit?: number;
+        offset?: number;
+        order?: Partial<Record<keyof T & string, 'ASC' | 'DESC'>>;
+    }): Promise<[T[], number]>;
+    create(data: Partial<T> | Partial<T>[]): Promise<T | T[]>;
+    update(data: Partial<T> & {
+        id: string;
+    }): Promise<T>;
+    delete(ids: string | string[]): Promise<void>;
+    softDelete(ids: string | string[]): Promise<Record<string, string[]>>;
+    restore(ids: string | string[]): Promise<void>;
+    upsertWithReplace(data: Partial<T>[], replaceFields?: string[], conflictTarget?: string[]): Promise<T[]>;
+}
+/**
+ * Service methods — plain async functions. No compensation wrapper needed.
+ * The framework auto-snapshots repo mutations for rollback.
+ */
+type ServiceMethods = Record<string, (...args: any[]) => Promise<any>>;
+/**
+ * Context passed to the service factory.
+ * - `db` — typed repository for CRUD operations
+ * - `log` — logger instance
+ */
+export interface ServiceFactoryContext<T> {
+    db: TypedRepository<T>;
+    log: ILoggerPort;
+}
+/**
+ * Service descriptor — the output of defineService().
+ * Contains metadata for bootstrap to instantiate the service.
+ */
+export interface ServiceDescriptor<E extends DmlEntity<any> = DmlEntity<any>, Methods = ServiceMethods> {
+    __type: 'service';
+    entity: E;
+    factory: (ctx: ServiceFactoryContext<InferEntity<E>>) => Methods;
+    $modelObjects: Record<string, E>;
+    /** Methods exposed to other modules via app.modules.*. If undefined, all methods are public. */
+    publicMethods?: string[];
+    /** Entity name (resolved from string or callback). */
+    _entityName?: string;
+}
+/**
+ * Type guard: is this value a ServiceDescriptor?
+ */
+export declare function isServiceDescriptor(value: unknown): value is ServiceDescriptor<any, any>;
+/**
+ * Entity name type — autocompletes from MantaGeneratedEntities (codegen),
+ * but accepts any string before codegen has run.
+ */
+type EntityNameArg = keyof MantaGeneratedEntities | (string & {});
+/**
+ * Define a service for a DML entity.
+ *
+ * ```ts
+ * export default defineService('product', ({ db, log }) => ({
+ *   publish: async (id: string) => {
+ *     await db.update({ id, status: 'published' })
+ *     log.info(`Product ${id} published`)
+ *   },
+ * }))
+ * ```
+ *
+ * Compensation is automatic — the repo snapshots state before every mutation.
+ */
+export declare function defineService<Methods extends ServiceMethods>(entity: EntityNameArg, factory: (ctx: ServiceFactoryContext<any>) => Methods, options?: {
+    publicMethods?: (keyof Methods & string)[];
+}): ServiceDescriptor<any, Methods>;
+/**
+ * @deprecated Use string form: `defineService('product', factory)`.
+ * Callback form kept for backward compatibility during migration.
+ */
+export declare function defineService<Methods extends ServiceMethods>(entitySelector: (model: ModelProxy) => ModelRef, factory: (ctx: ServiceFactoryContext<any>) => Methods, options?: {
+    publicMethods?: (keyof Methods & string)[];
+}): ServiceDescriptor<any, Methods>;
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/service/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/service/define.ts"],"names":[],"mappings":"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"}

package/dist/service/define.js

@@ -0,0 +1,45 @@
+// service.define() — Functional, typed API for defining module services.
+//
+// Services = mutations only (CQRS). Reads go through the Query Graph.
+// Compensation is automatic — the repo snapshots state before every mutation.
+// No service.method() needed. Just write async functions.
+//
+// Usage:
+//   export default defineService('product', ({ db, log }) => ({
+//     publish: async (id: string) => {
+//       await db.update({ id, status: 'published' })
+//       log.info(`Product ${id} published`)
+//     },
+//   }))
+import { createModelProxy } from '../link/index';
+/**
+ * Type guard: is this value a ServiceDescriptor?
+ */
+// biome-ignore lint/suspicious/noExplicitAny: type guard
+export function isServiceDescriptor(value) {
+    return typeof value === 'object' && value !== null && value.__type === 'service';
+}
+// ── Implementation ──────────────────────────────────────────────────
+// biome-ignore lint/suspicious/noExplicitAny: generic constraint for any async method
+export function defineService(entityOrSelector, factory, options) {
+    let entityName;
+    if (typeof entityOrSelector === 'string') {
+        entityName = entityOrSelector;
+    }
+    else {
+        // Legacy callback form
+        const proxy = createModelProxy();
+        const ref = entityOrSelector(proxy);
+        entityName = ref.entityName;
+    }
+    return {
+        __type: 'service',
+        // biome-ignore lint/suspicious/noExplicitAny: entity is resolved at boot time from _entityName
+        entity: null,
+        factory,
+        $modelObjects: {},
+        publicMethods: options?.publicMethods,
+        _entityName: entityName,
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/service/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/service/define.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,SAAS;AACT,gEAAgE;AAChE,uCAAuC;AACvC,qDAAqD;AACrD,4CAA4C;AAC5C,SAAS;AACT,QAAQ;AAKR,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAiEhD;;GAEG;AACH,yDAAyD;AACzD,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,MAAM,KAAK,SAAS,CAAA;AAC/G,CAAC;AAwCD,uEAAuE;AACvE,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAC3B,gBAAmE,EACnE,OAAqD,EACrD,OAAwD;IAExD,IAAI,UAAkB,CAAA;IAEtB,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;QACzC,UAAU,GAAG,gBAAgB,CAAA;IAC/B,CAAC;SAAM,CAAC;QACN,uBAAuB;QACvB,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAA;QAChC,MAAM,GAAG,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;QACnC,UAAU,GAAG,GAAG,CAAC,UAAU,CAAA;IAC7B,CAAC;IAED,OAAO;QACL,MAAM,EAAE,SAAkB;QAC1B,+FAA+F;QAC/F,MAAM,EAAE,IAAiC;QACzC,OAAO;QACP,aAAa,EAAE,EAAE;QACjB,aAAa,EAAE,OAAO,EAAE,aAAa;QACrC,WAAW,EAAE,UAAU;KACxB,CAAA;AACH,CAAC"}