@decaf-ts/core 0.18.0 → 0.19.0

package/lib/types/repository/errors.d.mts

@@ -0,0 +1,19 @@
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown when observer communication fails.
+ * @summary Represents a failure in observer communication between repositories.
+ * @param {string|Error} msg - The error message or Error object.
+ * @class ObserverError
+ * @category Errors
+ * @example
+ * try {
+ *   // Some repository observer operation
+ * } catch (error) {
+ *   if (error instanceof ObserverError) {
+ *     console.error('Observer communication failed:', error.message);
+ *   }
+ * }
+ */
+export declare class ObserverError extends InternalError {
+    constructor(msg: string | Error);
+}

package/lib/types/repository/index.d.cts

@@ -0,0 +1,12 @@
+/**
+ * @description Exports for the repository module.
+ * @summary This file exports all the necessary components for the repository functionality, including constants, decorators, and more.
+ * @module core/repository
+ */
+export * from "./constants.cjs";
+export * from "./decorators.cjs";
+export * from "./errors.cjs";
+export * from "./injectables.cjs";
+export * from "./Repository.cjs";
+export * from "./types.cjs";
+export * from "./utils.cjs";

package/lib/types/repository/index.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @description Exports for the repository module.
+ * @summary This file exports all the necessary components for the repository functionality, including constants, decorators, and more.
+ * @module core/repository
+ */
+export * from "./constants.js";
+export * from "./decorators.js";
+export * from "./errors.js";
+export * from "./injectables.js";
+export * from "./Repository.js";
+export * from "./types.js";
+export * from "./utils.js";

package/lib/types/repository/injectables.d.cts

@@ -0,0 +1,95 @@
+import { InjectableRegistryImp } from "@decaf-ts/injectable-decorators";
+import { Logger } from "@decaf-ts/logging";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Registry for injectable repositories with auto-resolution.
+ * @summary Provides an InjectableRegistry implementation that resolves repositories by model name or constructor. If a repository
+ * is not explicitly registered, it attempts to infer the correct repository using model metadata and the active or specified adapter flavour.
+ * @param {void} [constructor] No constructor parameters required; the superclass handles internal state.
+ * @class InjectablesRegistry
+ * @example
+ * // Basic usage: retrieve a repository by model name
+ * const registry = new InjectablesRegistry();
+ * const userRepo = registry.get<UserRepository>('User');
+ * // If UserRepository is registered, it will be returned. Otherwise, a repository will be created if a User model exists.
+ *
+ * // Retrieve by constructor and specify adapter flavour
+ * const repoByCtor = registry.get<UserRepository>(UserModel, 'ram');
+ *
+ * // Retrieve by symbol (e.g., injectable token)
+ * const token = Symbol.for('UserRepository');
+ * const byToken = registry.get<UserRepository>(token);
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Consumer
+ *   participant R as InjectablesRegistry
+ *   participant B as BaseRegistry
+ *   participant M as Model
+ *   participant A as Adapter
+ *   participant RP as Repository
+ *   C->>R: get(name, flavour?)
+ *   activate R
+ *   R->>B: super.get(name)
+ *   alt Found in base registry
+ *     B-->>R: injectable
+ *     R-->>C: injectable
+ *   else Not found
+ *     R->>M: Model.get(name)
+ *     alt Model found
+ *       R->>A: resolve flavour (from arg/metadata/current)
+ *       R->>RP: Repository.forModel(modelCtor, alias)
+ *       alt Repository instance
+ *         RP-->>R: repository instance
+ *         R-->>C: repository instance
+ *       else Repository ctor
+ *         R->>A: Adapter.get(resolvedFlavour) or Adapter.current
+ *         A-->>R: adapter instance
+ *         R->>RP: new repoCtor(adapter, modelCtor)
+ *         R-->>C: repository instance
+ *       end
+ *     else Model not found
+ *       R-->>C: undefined
+ *     end
+ *   end
+ */
+export declare class InjectablesRegistry extends InjectableRegistryImp {
+    private logger?;
+    protected get log(): Logger;
+    constructor();
+    /**
+     * @description Retrieve an injectable with repository auto-resolution.
+     * @summary Attempts to get an injectable from the base registry; if not found and the name refers to a known model, it
+     * resolves the appropriate repository using the specified flavour or model metadata, falling back to the current adapter when needed.
+     * @template T The injectable type to be returned.
+     * @param {string | symbol | Constructor<T>} name Token, model name, or constructor associated with the injectable or model.
+     * @param {string} [flavour] Optional adapter flavour (e.g., "ram"). If omitted, derives from metadata or current adapter.
+     * @return {T | undefined} The located or auto-created injectable instance; otherwise undefined if it cannot be resolved.
+     * @mermaid
+     * sequenceDiagram
+     *   participant G as get(name, flavour?)
+     *   participant BR as BaseRegistry
+     *   participant M as Model
+     *   participant A as Adapter
+     *   participant RP as Repository
+     *   G->>BR: super.get(name)
+     *   alt Found
+     *     BR-->>G: injectable
+     *   else Not found
+     *     G->>M: derive modelCtor from name
+     *     alt modelCtor resolved
+     *       G->>A: resolve flavour (arg | metadata | current)
+     *       G->>RP: Repository.forModel(modelCtor, alias)
+     *       alt returns instance
+     *         RP-->>G: Repository instance
+     *       else returns ctor
+     *         G->>A: Adapter.get(flavour) | Adapter.current
+     *         A-->>G: adapter instance
+     *         G->>RP: new repoCtor(adapter, modelCtor)
+     *       end
+     *     else no modelCtor
+     *       G-->>G: return undefined
+     *     end
+     *   end
+     */
+    get<T>(name: symbol | Constructor<T> | string, flavour?: string): T | undefined;
+}

package/lib/types/repository/injectables.d.mts

@@ -0,0 +1,95 @@
+import { InjectableRegistryImp } from "@decaf-ts/injectable-decorators";
+import { Logger } from "@decaf-ts/logging";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Registry for injectable repositories with auto-resolution.
+ * @summary Provides an InjectableRegistry implementation that resolves repositories by model name or constructor. If a repository
+ * is not explicitly registered, it attempts to infer the correct repository using model metadata and the active or specified adapter flavour.
+ * @param {void} [constructor] No constructor parameters required; the superclass handles internal state.
+ * @class InjectablesRegistry
+ * @example
+ * // Basic usage: retrieve a repository by model name
+ * const registry = new InjectablesRegistry();
+ * const userRepo = registry.get<UserRepository>('User');
+ * // If UserRepository is registered, it will be returned. Otherwise, a repository will be created if a User model exists.
+ *
+ * // Retrieve by constructor and specify adapter flavour
+ * const repoByCtor = registry.get<UserRepository>(UserModel, 'ram');
+ *
+ * // Retrieve by symbol (e.g., injectable token)
+ * const token = Symbol.for('UserRepository');
+ * const byToken = registry.get<UserRepository>(token);
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Consumer
+ *   participant R as InjectablesRegistry
+ *   participant B as BaseRegistry
+ *   participant M as Model
+ *   participant A as Adapter
+ *   participant RP as Repository
+ *   C->>R: get(name, flavour?)
+ *   activate R
+ *   R->>B: super.get(name)
+ *   alt Found in base registry
+ *     B-->>R: injectable
+ *     R-->>C: injectable
+ *   else Not found
+ *     R->>M: Model.get(name)
+ *     alt Model found
+ *       R->>A: resolve flavour (from arg/metadata/current)
+ *       R->>RP: Repository.forModel(modelCtor, alias)
+ *       alt Repository instance
+ *         RP-->>R: repository instance
+ *         R-->>C: repository instance
+ *       else Repository ctor
+ *         R->>A: Adapter.get(resolvedFlavour) or Adapter.current
+ *         A-->>R: adapter instance
+ *         R->>RP: new repoCtor(adapter, modelCtor)
+ *         R-->>C: repository instance
+ *       end
+ *     else Model not found
+ *       R-->>C: undefined
+ *     end
+ *   end
+ */
+export declare class InjectablesRegistry extends InjectableRegistryImp {
+    private logger?;
+    protected get log(): Logger;
+    constructor();
+    /**
+     * @description Retrieve an injectable with repository auto-resolution.
+     * @summary Attempts to get an injectable from the base registry; if not found and the name refers to a known model, it
+     * resolves the appropriate repository using the specified flavour or model metadata, falling back to the current adapter when needed.
+     * @template T The injectable type to be returned.
+     * @param {string | symbol | Constructor<T>} name Token, model name, or constructor associated with the injectable or model.
+     * @param {string} [flavour] Optional adapter flavour (e.g., "ram"). If omitted, derives from metadata or current adapter.
+     * @return {T | undefined} The located or auto-created injectable instance; otherwise undefined if it cannot be resolved.
+     * @mermaid
+     * sequenceDiagram
+     *   participant G as get(name, flavour?)
+     *   participant BR as BaseRegistry
+     *   participant M as Model
+     *   participant A as Adapter
+     *   participant RP as Repository
+     *   G->>BR: super.get(name)
+     *   alt Found
+     *     BR-->>G: injectable
+     *   else Not found
+     *     G->>M: derive modelCtor from name
+     *     alt modelCtor resolved
+     *       G->>A: resolve flavour (arg | metadata | current)
+     *       G->>RP: Repository.forModel(modelCtor, alias)
+     *       alt returns instance
+     *         RP-->>G: Repository instance
+     *       else returns ctor
+     *         G->>A: Adapter.get(flavour) | Adapter.current
+     *         A-->>G: adapter instance
+     *         G->>RP: new repoCtor(adapter, modelCtor)
+     *       end
+     *     else no modelCtor
+     *       G-->>G: return undefined
+     *     end
+     *   end
+     */
+    get<T>(name: symbol | Constructor<T> | string, flavour?: string): T | undefined;
+}

package/lib/types/repository/types.d.cts

@@ -0,0 +1,28 @@
+import { Cascade, OrderDirection } from "./constants.cjs";
+/**
+ * @description Metadata for cascade operations on related entities.
+ * @summary Defines how update and delete operations should cascade to related entities.
+ * @typedef CascadeMetadata
+ * @property {Cascade} update - Determines cascade behavior for update operations.
+ * @property {Cascade} delete - Determines cascade behavior for delete operations.
+ * @memberOf module:core
+ */
+export type CascadeMetadata = {
+    update: Cascade;
+    delete: Cascade;
+};
+export type IndexMetadata = {
+    name?: string;
+    directions?: OrderDirection[2];
+    compositions?: string[];
+};
+/**
+ * @description Metadata for a named index that extends IndexMetadata.
+ * @summary Extends IndexMetadata with a suffix to identify the index.
+ * @typedef NamedIndexMetadata
+ * @property {string} suffix - The suffix to append to the index name.
+ * @memberOf module:core
+ */
+export type NamedIndexMetadata = IndexMetadata & {
+    suffix: string;
+};

package/lib/types/repository/types.d.mts

@@ -0,0 +1,28 @@
+import { Cascade, OrderDirection } from "./constants.js";
+/**
+ * @description Metadata for cascade operations on related entities.
+ * @summary Defines how update and delete operations should cascade to related entities.
+ * @typedef CascadeMetadata
+ * @property {Cascade} update - Determines cascade behavior for update operations.
+ * @property {Cascade} delete - Determines cascade behavior for delete operations.
+ * @memberOf module:core
+ */
+export type CascadeMetadata = {
+    update: Cascade;
+    delete: Cascade;
+};
+export type IndexMetadata = {
+    name?: string;
+    directions?: OrderDirection[2];
+    compositions?: string[];
+};
+/**
+ * @description Metadata for a named index that extends IndexMetadata.
+ * @summary Extends IndexMetadata with a suffix to identify the index.
+ * @typedef NamedIndexMetadata
+ * @property {string} suffix - The suffix to append to the index name.
+ * @memberOf module:core
+ */
+export type NamedIndexMetadata = IndexMetadata & {
+    suffix: string;
+};

package/lib/types/repository/utils.d.cts

@@ -0,0 +1,36 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Generates a unique injectable name for a repository.
+ * @summary Creates a standardized injectable token for repositories using the adapter flavour and model table name.
+ * This helps the DI system register and resolve repository instances consistently across adapters.
+ * @template T The model type that extends Model.
+ * @param {Constructor<T> | T} model The model constructor or instance from which to derive the table name.
+ * @param {string} [flavour] Optional adapter flavour/alias. If omitted, it is read from model metadata.
+ * @return {string} A namespaced injectable token for the repository (e.g., "db:repo:ram:users").
+ * @throws {InternalError} If the flavour cannot be determined from arguments or metadata.
+ * @function generateInjectableNameForRepository
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Caller
+ *   participant U as generateInjectableNameForRepository
+ *   participant R as Reflect Metadata
+ *   participant A as Adapter
+ *   participant S as String Formatter
+ *   C->>U: call(model, flavour?)
+ *   alt flavour provided
+ *     U-->>U: use provided flavour
+ *   else flavour not provided
+ *     U->>A: ADAPTER
+ *     U->>R: getMetadata(key, model|model.ctor)
+ *     alt metadata present
+ *       R-->>U: flavour
+ *     else missing
+ *       U-->>C: throw InternalError
+ *     end
+ *   end
+ *   U->>S: sf(INJECTABLE, flavour, Model.tableName(model))
+ *   S-->>C: token string
+ * @memberOf module:core
+ */
+export declare function generateInjectableNameForRepository<T extends Model>(model: Constructor<T> | T, flavour?: string): string;

package/lib/types/repository/utils.d.mts

@@ -0,0 +1,36 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Generates a unique injectable name for a repository.
+ * @summary Creates a standardized injectable token for repositories using the adapter flavour and model table name.
+ * This helps the DI system register and resolve repository instances consistently across adapters.
+ * @template T The model type that extends Model.
+ * @param {Constructor<T> | T} model The model constructor or instance from which to derive the table name.
+ * @param {string} [flavour] Optional adapter flavour/alias. If omitted, it is read from model metadata.
+ * @return {string} A namespaced injectable token for the repository (e.g., "db:repo:ram:users").
+ * @throws {InternalError} If the flavour cannot be determined from arguments or metadata.
+ * @function generateInjectableNameForRepository
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Caller
+ *   participant U as generateInjectableNameForRepository
+ *   participant R as Reflect Metadata
+ *   participant A as Adapter
+ *   participant S as String Formatter
+ *   C->>U: call(model, flavour?)
+ *   alt flavour provided
+ *     U-->>U: use provided flavour
+ *   else flavour not provided
+ *     U->>A: ADAPTER
+ *     U->>R: getMetadata(key, model|model.ctor)
+ *     alt metadata present
+ *       R-->>U: flavour
+ *     else missing
+ *       U-->>C: throw InternalError
+ *     end
+ *   end
+ *   U->>S: sf(INJECTABLE, flavour, Model.tableName(model))
+ *   S-->>C: token string
+ * @memberOf module:core
+ */
+export declare function generateInjectableNameForRepository<T extends Model>(model: Constructor<T> | T, flavour?: string): string;

package/lib/types/services/ModelService.d.cts

@@ -0,0 +1,45 @@
+import { type Constructor } from "@decaf-ts/decoration";
+import { Model, type ModelConstructor } from "@decaf-ts/decorator-validation";
+import { type Repo } from "../repository/Repository.cjs";
+import { Service } from "./services.cjs";
+import type { AllOperationKeys, ContextOf, EventIds, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types.cjs";
+import { type IRepository, type PrimaryKeyType } from "@decaf-ts/db-decorators";
+import type { ContextualArgs, ContextualizedArgs, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.cjs";
+import { OrderDirection } from "../repository/constants.cjs";
+import { type DirectionLimitOffset } from "../query/types.cjs";
+import { type Observer } from "../interfaces/index.cjs";
+import { SelectSelector, WhereOption } from "../query/index.cjs";
+export type ArrayMode = "one" | "many";
+export declare class ModelService<M extends Model<boolean>, R extends Repo<M> = Repo<M>> extends Service implements IRepository<M, ContextOf<R>>, PersistenceObservable<ContextOf<R>>, PersistenceObserver<ContextOf<R>> {
+    private readonly clazz;
+    protected _repository: R;
+    get class(): Constructor<M>;
+    get repo(): R;
+    constructor(clazz: Constructor<M>, name?: string);
+    static getService<M extends Model<boolean>, S extends ModelService<M>>(name: string | symbol | Constructor<M>): S;
+    create(model: M, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    createAll(models: M[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    delete(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    deleteAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    read(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    readAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    query<M, R extends ArrayMode = "one">(methodName: string, ...args: unknown[]): Promise<R extends "one" ? M : M[]>;
+    update(model: M, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    updateAll(models: M[], ...args: any[]): Promise<M[]>;
+    select<S extends readonly SelectSelector<M>[]>(): WhereOption<M, M[]>;
+    select<S extends readonly SelectSelector<M>[]>(selector: readonly [...S]): WhereOption<M, Pick<M, S[number]>[]>;
+    listBy(key: keyof M, order: OrderDirection, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    paginateBy(key: keyof M, order: OrderDirection, ref: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<ContextOf<R>>): Promise<import("..").SerializedPage<M>>;
+    findOneBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    findBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    findByPaginate(key: keyof M, value: any, ref: DirectionLimitOffset, ...args: MaybeContextualArg<ContextOf<R>>): Promise<import("..").SerializedPage<M>>;
+    statement(name: string, ...args: MaybeContextualArg<ContextOf<R>>): Promise<any>;
+    static forModel<M extends Model<boolean>, S extends ModelService<M>>(this: new (model: ModelConstructor<M>) => S, model: ModelConstructor<M>, alias?: string | symbol): S;
+    refresh(table: Constructor<M>, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<ContextOf<R>>): Promise<void>;
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    unObserve(observer: Observer): void;
+    updateObservers(model: Constructor, operation: AllOperationKeys, ids: EventIds, ...args: ContextualArgs<ContextOf<R>>): Promise<void>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD): ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>>;
+}

package/lib/types/services/ModelService.d.mts

@@ -0,0 +1,45 @@
+import { type Constructor } from "@decaf-ts/decoration";
+import { Model, type ModelConstructor } from "@decaf-ts/decorator-validation";
+import { type Repo } from "../repository/Repository.js";
+import { Service } from "./services.js";
+import type { AllOperationKeys, ContextOf, EventIds, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types.js";
+import { type IRepository, type PrimaryKeyType } from "@decaf-ts/db-decorators";
+import type { ContextualArgs, ContextualizedArgs, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.js";
+import { OrderDirection } from "../repository/constants.js";
+import { type DirectionLimitOffset } from "../query/types.js";
+import { type Observer } from "../interfaces/index.js";
+import { SelectSelector, WhereOption } from "../query/index.js";
+export type ArrayMode = "one" | "many";
+export declare class ModelService<M extends Model<boolean>, R extends Repo<M> = Repo<M>> extends Service implements IRepository<M, ContextOf<R>>, PersistenceObservable<ContextOf<R>>, PersistenceObserver<ContextOf<R>> {
+    private readonly clazz;
+    protected _repository: R;
+    get class(): Constructor<M>;
+    get repo(): R;
+    constructor(clazz: Constructor<M>, name?: string);
+    static getService<M extends Model<boolean>, S extends ModelService<M>>(name: string | symbol | Constructor<M>): S;
+    create(model: M, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    createAll(models: M[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    delete(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    deleteAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    read(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    readAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    query<M, R extends ArrayMode = "one">(methodName: string, ...args: unknown[]): Promise<R extends "one" ? M : M[]>;
+    update(model: M, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    updateAll(models: M[], ...args: any[]): Promise<M[]>;
+    select<S extends readonly SelectSelector<M>[]>(): WhereOption<M, M[]>;
+    select<S extends readonly SelectSelector<M>[]>(selector: readonly [...S]): WhereOption<M, Pick<M, S[number]>[]>;
+    listBy(key: keyof M, order: OrderDirection, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    paginateBy(key: keyof M, order: OrderDirection, ref: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<ContextOf<R>>): Promise<import("..").SerializedPage<M>>;
+    findOneBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M>;
+    findBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<R>>): Promise<M[]>;
+    findByPaginate(key: keyof M, value: any, ref: DirectionLimitOffset, ...args: MaybeContextualArg<ContextOf<R>>): Promise<import("..").SerializedPage<M>>;
+    statement(name: string, ...args: MaybeContextualArg<ContextOf<R>>): Promise<any>;
+    static forModel<M extends Model<boolean>, S extends ModelService<M>>(this: new (model: ModelConstructor<M>) => S, model: ModelConstructor<M>, alias?: string | symbol): S;
+    refresh(table: Constructor<M>, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<ContextOf<R>>): Promise<void>;
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    unObserve(observer: Observer): void;
+    updateObservers(model: Constructor, operation: AllOperationKeys, ids: EventIds, ...args: ContextualArgs<ContextOf<R>>): Promise<void>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD): ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<this["repo"]>, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<ContextOf<this["repo"]>, ARGS, METHOD extends string ? true : false>>;
+}

package/lib/types/services/PersistenceService.d.cts

@@ -0,0 +1,17 @@
+import { ClientBasedService } from "./services.cjs";
+import { Adapter } from "../persistence/Adapter.cjs";
+import { ConfigOf, ContextOf } from "../persistence/types.cjs";
+import { MaybeContextualArg } from "../utils/ContextualLoggedClass.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+export declare class PersistenceService<A extends Adapter<any, any, any, any>> extends ClientBasedService<A[], [
+    Constructor<A>,
+    ConfigOf<A>,
+    ...args: any[]
+][], ContextOf<A>> {
+    constructor();
+    for(conf: any, ...args: any[]): this;
+    initialize(...args: MaybeContextualArg<ContextOf<A>>): Promise<{
+        config: [Constructor<A>, ConfigOf<A>, ...args: any[]][];
+        client: A[];
+    }>;
+}

package/lib/types/services/PersistenceService.d.mts

@@ -0,0 +1,17 @@
+import { ClientBasedService } from "./services.js";
+import { Adapter } from "../persistence/Adapter.js";
+import { ConfigOf, ContextOf } from "../persistence/types.js";
+import { MaybeContextualArg } from "../utils/ContextualLoggedClass.js";
+import { Constructor } from "@decaf-ts/decoration";
+export declare class PersistenceService<A extends Adapter<any, any, any, any>> extends ClientBasedService<A[], [
+    Constructor<A>,
+    ConfigOf<A>,
+    ...args: any[]
+][], ContextOf<A>> {
+    constructor();
+    for(conf: any, ...args: any[]): this;
+    initialize(...args: MaybeContextualArg<ContextOf<A>>): Promise<{
+        config: [Constructor<A>, ConfigOf<A>, ...args: any[]][];
+        client: A[];
+    }>;
+}

package/lib/types/services/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * @description Exports for the services module.
+ * @summary This file exports all the necessary components for the services functionality, including ModelService, PersistenceService, and services.
+ * @module core/services
+ */
+export * from "./ModelService.cjs";
+export * from "./PersistenceService.cjs";
+export * from "./services.cjs";

package/lib/types/services/index.d.mts

@@ -0,0 +1,8 @@
+/**
+ * @description Exports for the services module.
+ * @summary This file exports all the necessary components for the services functionality, including ModelService, PersistenceService, and services.
+ * @module core/services
+ */
+export * from "./ModelService.js";
+export * from "./PersistenceService.js";
+export * from "./services.js";

package/lib/types/services/services.d.cts

@@ -0,0 +1,96 @@
+import type { AllOperationKeys, ContextFlags, EventIds, FlagsOf, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types.cjs";
+import { Context } from "../persistence/Context.cjs";
+import { ContextualArgs, ContextualizedArgs, ContextualLoggedClass, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import type { Observer } from "../interfaces/Observer.cjs";
+import { ObserverHandler } from "../persistence/ObserverHandler.cjs";
+export declare abstract class Service<C extends Context<ContextFlags<any>> = Context<ContextFlags<any>>> extends ContextualLoggedClass<C> implements PersistenceObservable<C>, PersistenceObserver<C> {
+    readonly name?: string | undefined;
+    protected observers: Observer[];
+    protected observerHandler?: ObserverHandler;
+    protected constructor(name?: string | undefined);
+    for(conf: any, ...args: any[]): this;
+    override(conf: any, ...args: any[]): this;
+    /**
+     * @description Registers an observer for this repository.
+     * @summary Adds an observer that will be notified of changes to models in this repository.
+     * @param {Observer} observer - The observer to register.
+     * @param {ObserverFilter} [filter] - Optional filter to limit which events the observer receives.
+     * @return {void}
+     * @see {Observable#observe}
+     */
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    /**
+     * @description Unregisters an observer from this repository.
+     * @summary Removes an observer so it will no longer receive notifications of changes.
+     * @param {Observer} observer - The observer to unregister.
+     * @return {void}
+     * @throws {InternalError} If the observer handler is not initialized.
+     * @see {Observable#unObserve}
+     */
+    unObserve(observer: Observer): void;
+    /**
+     * @description Notifies all observers of an event.
+     * @summary Updates all registered observers with information about a database event.
+     * @param {string} table - The table name where the event occurred.
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of event that occurred.
+     * @param {EventIds} id - The ID or IDs of the affected records.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<void>} A promise that resolves when all observers have been notified.
+     * @throws {InternalError} If the observer handler is not initialized.
+     */
+    updateObservers(table: Constructor<any> | string, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<C>): Promise<void>;
+    /**
+     * @description Creates repository flags for an operation
+     * @summary Generates a set of flags that describe a database operation, combining default flags with overrides
+     * @template F - The Repository Flags type
+     * @template M - The model type
+     * @param {OperationKeys} operation - The type of operation being performed
+     * @param {Partial<F>} flags - Custom flag overrides
+     * @param {...any[]} args - Additional arguments
+     * @return {Promise<F>} The complete set of flags
+     */
+    protected flags(operation: string, flags: Partial<FlagsOf<C>>, ...args: any[]): Promise<FlagsOf<C>>;
+    /**
+     * @description Alias for updateObservers.
+     * @summary Notifies all observers of an event (alias for updateObservers).
+     * @param {string} table - The table name where the event occurred.
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of event that occurred.
+     * @param {EventIds} id - The ID or IDs of the affected records.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<void>} A promise that resolves when all observers have been notified.
+     */
+    refresh(table: Constructor<any> | string, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<C>): Promise<void>;
+    /**
+     * @description The context constructor for this adapter
+     * @summary Reference to the context class constructor used by this adapter
+     */
+    protected readonly Context: Constructor<C>;
+    context(operation: ((...args: any[]) => any) | string, overrides: Partial<FlagsOf<C>>, ...args: MaybeContextualArg<Context<any>>): Promise<C>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD): ContextualizedArgs<CONTEXT, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FlagsOf<CONTEXT>>): ContextualizedArgs<CONTEXT, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<CONTEXT extends Context<any> = C, ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<CONTEXT, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FlagsOf<CONTEXT>>): Promise<ContextualizedArgs<CONTEXT, ARGS, METHOD extends string ? true : false>>;
+    /**
+     * @description Retrieves a Service instance by name/class
+     * @summary Looks up and returns a cached API instance by its name or constructor
+     * @template A Type extending Api
+     * @param {string | Constructor<A>} name - Name of the API or its constructor
+     * @return {A} The requested API instance
+     */
+    static get<A extends Service>(name: string | symbol | Constructor<A>): A;
+    static boot<C extends Context<any> = any>(...args: MaybeContextualArg<C>): Promise<void>;
+    static shutdown<C extends Context<any> = any>(...args: MaybeContextualArg<C>): Promise<void>;
+}
+export declare abstract class ClientBasedService<CLIENT, CONF, C extends Context<any> = any> extends Service {
+    protected _client?: CLIENT;
+    protected _config?: CONF;
+    protected constructor();
+    boot(...args: MaybeContextualArg<C>): Promise<void>;
+    abstract initialize(...args: ContextualArgs<C>): Promise<{
+        config: CONF;
+        client: CLIENT;
+    }>;
+    protected get config(): CONF;
+    get client(): CLIENT;
+    shutdown(...args: MaybeContextualArg<C>): Promise<void>;
+}