@cullet/erp-core 1.0.10 → 1.1.0

package/src/core/application/use-case.ts

@@ -1,8 +1,31 @@
 import { type ContractVersion, version } from "../versioning/version.js";
 import type { Result } from "../result/result.js";
 
+import type { LoggerPort } from "./ports/logger.port.js";
+import type { MetricsPort } from "./ports/metrics.port.js";
+import type { TracerPort } from "./ports/tracer.port.js";
+
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Observability adapters a use case may opt into.
+ *
+ * All fields are optional: a use case that provides none keeps the plain
+ * `input → Result` behavior with zero overhead. When provided, {@link UseCase.run}
+ * instruments every execution around `execute()` — opening a span, recording
+ * duration, counting outcomes, and logging business/unexpected failures.
+ */
+interface UseCaseObservability {
+    readonly logger?: LoggerPort;
+    readonly metrics?: MetricsPort;
+    readonly tracer?: TracerPort;
+}
+
+const EXECUTION_COUNTER = "use_case.executions";
+const DURATION_HISTOGRAM = "use_case.duration_ms";
+
+type ExecutionOutcome = "ok" | "error" | "exception";
+
 @version("1.0")
 abstract class UseCase<
     Input = void,
@@ -14,11 +37,119 @@ abstract class UseCase<
         return UseCase.CONTRACT_VERSION;
     }
 
+    /**
+     * Runs the use case.
+     *
+     * `run()` is the single seam every use case crosses, so it is where
+     * cross-cutting instrumentation lives. When {@link observability} exposes
+     * any adapter, the call to `execute()` is wrapped with tracing, metrics and
+     * failure logging; otherwise it delegates directly with no overhead.
+     *
+     * Observability is strictly side-effecting: a misbehaving adapter never
+     * changes the business result nor masks a thrown error — its own failures
+     * are swallowed.
+     */
     public async run(input: Input): Promise<Output> {
-        return await this.execute(input);
+        const observability = this.observability();
+        if (
+            !observability.logger &&
+            !observability.metrics &&
+            !observability.tracer
+        ) {
+            return await this.execute(input);
+        }
+
+        return await this.runInstrumented(input, observability);
+    }
+
+    /**
+     * Adapters used to instrument {@link run}. Override to opt a use case into
+     * tracing/metrics/logging. Returns an empty object by default, which keeps
+     * the plain delegating behavior.
+     */
+    protected observability(): UseCaseObservability {
+        return {};
+    }
+
+    /**
+     * Stable identity used for span names and metric labels. Defaults to the
+     * runtime class name; override when bundling/minification would otherwise
+     * erase a meaningful name.
+     */
+    protected get useCaseName(): string {
+        return this.constructor.name;
     }
 
     protected abstract execute(input: Input): MaybePromise<Output>;
+
+    private async runInstrumented(
+        input: Input,
+        observability: UseCaseObservability,
+    ): Promise<Output> {
+        const { logger, metrics, tracer } = observability;
+        const name = this.useCaseName;
+        const span = safely(() =>
+            tracer?.startSpan(name, { "use_case.name": name }),
+        );
+        const startedAt = Date.now();
+
+        try {
+            const output = await this.execute(input);
+            const outcome: ExecutionOutcome = output.isOk() ? "ok" : "error";
+
+            if (outcome === "error") {
+                safely(() =>
+                    logger?.warn(`${name} returned a business error`, {
+                        useCase: name,
+                    }),
+                );
+            }
+            safely(() => span?.setAttribute("use_case.outcome", outcome));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome,
+                }),
+            );
+
+            return output;
+        } catch (error) {
+            safely(() =>
+                logger?.error(`${name} threw an unexpected error`, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.setAttribute("use_case.outcome", "exception"));
+            safely(() => span?.recordException(error));
+            safely(() =>
+                metrics?.counter(EXECUTION_COUNTER, 1, {
+                    useCase: name,
+                    outcome: "exception",
+                }),
+            );
+
+            throw error;
+        } finally {
+            safely(() =>
+                metrics?.histogram(DURATION_HISTOGRAM, Date.now() - startedAt, {
+                    useCase: name,
+                }),
+            );
+            safely(() => span?.end());
+        }
+    }
+}
+
+/**
+ * Invokes an observability side effect, isolating any adapter failure so it
+ * cannot alter the use case outcome.
+ */
+function safely<R>(effect: () => R): R | undefined {
+    try {
+        return effect();
+    } catch {
+        return undefined;
+    }
 }
 
-export { type MaybePromise, UseCase };
+export { type MaybePromise, UseCase, type UseCaseObservability };

package/src/core/domain/entity.ts

@@ -3,6 +3,14 @@ import { assertValidAggregateVersion } from "../shared/aggregate-version.js";
 import { assertValidDate, cloneDate } from "../shared/temporal-guards.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
+/**
+ * The minimal persisted shape needed to reconstitute an {@link Entity}.
+ *
+ * This is the contract between storage and the domain: a repository maps a row
+ * (or document) onto these four fields and hands them to a subclass constructor.
+ * `aggregateVersion` travels with the state so optimistic-concurrency checks
+ * survive a round-trip through the database.
+ */
 interface EntityState<TIdentifier> {
     readonly id: TIdentifier;
     readonly createdAt: Date;
@@ -10,6 +18,20 @@ interface EntityState<TIdentifier> {
     readonly aggregateVersion: number;
 }
 
+/**
+ * Base class for domain entities — objects defined by a stable identity rather
+ * than by their attributes. Two entities are "the same" when their `id`
+ * matches, even if every other field differs; this is the opposite of a
+ * {@link ValueObject}, which is defined entirely by its contents.
+ *
+ * The class owns the bookkeeping common to every aggregate root: a creation
+ * timestamp that never changes, a last-modified timestamp, and an
+ * `aggregateVersion` counter used for optimistic concurrency control. All three
+ * are validated on construction and the dates are defensively cloned, so an
+ * entity can never be built into — or leak — an inconsistent temporal state.
+ *
+ * @typeParam TIdentifier - The identity type (e.g. a branded string id or a VO).
+ */
 @version("1.0")
 abstract class Entity<TIdentifier> {
     declare public static readonly CONTRACT_VERSION: ContractVersion;
@@ -19,6 +41,20 @@ abstract class Entity<TIdentifier> {
     private _updatedAt: Date;
     private _aggregateVersion: number;
 
+    /**
+     * Reconstitutes an entity from its persisted {@link EntityState}.
+     *
+     * Validates the temporal invariants up front so an invalid entity is
+     * impossible to construct: both dates must be valid, the aggregate version
+     * must be a non-negative integer, and `updatedAt` may not predate
+     * `createdAt`. Both dates are cloned on the way in so a later mutation of
+     * the caller's `Date` objects cannot reach into the entity's internal state.
+     *
+     * Declared `protected` because entities are reconstituted through a
+     * subclass factory, never instantiated directly by application code.
+     *
+     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+     */
     protected constructor(state: EntityState<TIdentifier>) {
         assertValidDate("createdAt", state.createdAt);
         assertValidDate("updatedAt", state.updatedAt);
@@ -36,26 +72,61 @@ abstract class Entity<TIdentifier> {
         this._aggregateVersion = state.aggregateVersion;
     }
 
+    /** The entity's stable identity — the basis for equality between entities. */
     public get id(): TIdentifier {
         return this._id;
     }
 
+    /**
+     * When the entity was first created.
+     *
+     * Returns a clone so callers cannot mutate the entity's internal `Date`;
+     * the value is fixed at construction and never changes thereafter.
+     */
     public get createdAt(): Date {
         return cloneDate(this._createdAt);
     }
 
+    /**
+     * When the entity was last modified.
+     *
+     * Returns a clone for the same encapsulation reason as {@link createdAt};
+     * the underlying value advances only through {@link markAsModified}.
+     */
     public get updatedAt(): Date {
         return cloneDate(this._updatedAt);
     }
 
+    /**
+     * Monotonic counter incremented on every mutation, used for optimistic
+     * concurrency control: a writer reads this value, and the persistence layer
+     * rejects the write if the stored version has moved on in the meantime.
+     */
     public get aggregateVersion(): number {
         return this._aggregateVersion;
     }
 
+    /**
+     * The schema/contract version stamped on this entity type by the
+     * `@version` decorator — used to detect and migrate state persisted under
+     * an older shape.
+     */
     public get contractVersion(): ContractVersion {
         return Entity.CONTRACT_VERSION;
     }
 
+    /**
+     * The single seam through which an entity records a mutation: it advances
+     * `updatedAt` and bumps {@link aggregateVersion} by one. Subclasses must
+     * call this from every state-changing method so the version counter stays
+     * an accurate optimistic-lock token.
+     *
+     * @param updatedAt - The modification instant; defaults to now. Validated
+     *   and required not to predate `createdAt`, preserving the same invariant
+     *   the constructor enforces.
+     * @returns The new aggregate version after the increment.
+     * @throws {InvariantViolationException} When `updatedAt` is earlier than `createdAt`.
+     */
     protected markAsModified(updatedAt: Date = new Date()): number {
         assertValidDate("updatedAt", updatedAt);
 

package/src/core/domain/value-object.ts

@@ -1,15 +1,41 @@
 import { type DeepReadonly, makeImmutable } from "../shared/immutable.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
+/**
+ * Base class for value objects — domain concepts defined entirely by their
+ * contents, with no identity of their own. Two value objects are
+ * interchangeable when they hold equal data, which is the opposite of an
+ * {@link Entity} (compared by id). Money, a CPF, a date range: replacing one
+ * instance with an equal one changes nothing about the model.
+ *
+ * Immutability is the defining guarantee here. The wrapped `value` is
+ * deep-frozen on construction, so a value object can be shared freely without
+ * any risk of a consumer mutating shared state. Subclasses seal the instance
+ * itself with {@link finalize} once their own fields are set.
+ *
+ * @typeParam T - The shape of the wrapped data.
+ * @typeParam P - The primitive form produced by {@link toPrimitive} / {@link toJSON}.
+ */
 @version("1.0")
 abstract class ValueObject<T, P> {
     declare public static readonly CONTRACT_VERSION: ContractVersion;
+
+    /** The wrapped data, deep-frozen so it can never be mutated after construction. */
     public readonly value: DeepReadonly<T>;
 
+    /**
+     * Wraps `value`, deep-freezing it so the value object is immutable from the
+     * moment it exists. Declared `protected` because value objects are built
+     * through a validating subclass factory, never instantiated directly.
+     */
     protected constructor(value: T) {
         this.value = makeImmutable(value);
     }
 
+    /**
+     * The schema/contract version stamped on this value-object type by the
+     * `@version` decorator — used to detect state persisted under an older shape.
+     */
     public get contractVersion(): ContractVersion {
         return ValueObject.CONTRACT_VERSION;
     }
@@ -28,12 +54,27 @@ abstract class ValueObject<T, P> {
         Object.freeze(this);
     }
 
+    /**
+     * Hook for `JSON.stringify`. Delegates to {@link toPrimitive} so a value
+     * object serializes to its primitive form rather than exposing the internal
+     * `value` wrapper.
+     */
     public toJSON(): P {
         return this.toPrimitive();
     }
 
+    /**
+     * Compares this value object with another by content. Because value objects
+     * carry no identity, subclasses implement equality over the wrapped data
+     * (typically the primitive form), so two independently constructed instances
+     * holding the same data are considered equal.
+     */
     public abstract equals(other: this): boolean;
 
+    /**
+     * Projects the value object down to a plain, serializable primitive form —
+     * the representation suitable for persistence, transport, or comparison.
+     */
     public abstract toPrimitive(): P;
 }
 

package/src/core/errors/app-error.ts

@@ -12,6 +12,22 @@ import { assertJsonSafeMetadata } from "./utils/index.js";
 // AppError (abstract base class)
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Root of the application/domain error hierarchy. Every error the system raises
+ * on purpose extends `AppError`, which gives callers a single `instanceof` to
+ * catch and a uniform, serializable shape to log and transport.
+ *
+ * Beyond the native `Error` message it carries a stable `code` (the contract the
+ * outside world matches on), an optional non-leaking `publicMessage`, a
+ * severity, JSON-safe `metadata`, and the correlation/request/command ids that
+ * stitch an error back to the request that produced it. The metadata is
+ * validated as JSON-safe on construction, so a logger can serialize any
+ * `AppError` without hitting a circular reference or a non-serializable value.
+ *
+ * Abstract on purpose: callers should throw a specific subclass (e.g.
+ * {@link ValidationError}, {@link NotFoundError}) so the `code` and shape are
+ * meaningful, never a bare `AppError`.
+ */
 abstract class AppError extends Error {
     public readonly code: string;
     public readonly cause?: unknown;
@@ -36,6 +52,23 @@ abstract class AppError extends Error {
      */
     public readonly commandId?: string;
 
+    /**
+     * Builds the common error envelope shared by every subclass.
+     *
+     * `name` is taken from `new.target` so the thrown instance reports its
+     * concrete subclass name (not `"AppError"`), and the prototype is re-pinned
+     * via `setPrototypeOf` so `instanceof` keeps working after transpilation to
+     * older targets where extending built-ins breaks the chain. `createdAtIso`
+     * defaults to now, and `metadata` is validated as JSON-safe so the error is
+     * always serializable.
+     *
+     * Declared `protected`: instantiate a concrete subclass, never `AppError`.
+     *
+     * @param message - The internal, developer-facing message.
+     * @param code - The stable machine-readable code callers match on.
+     * @param options - Optional cause, metadata, severity, and correlation ids.
+     * @throws When `options.metadata` contains a value that is not JSON-safe.
+     */
     protected constructor(
         message: string,
         code: string,

package/src/core/errors/authorization-error.ts

@@ -61,6 +61,19 @@ type AuthorizationErrorFactoryOptions = Omit<
 // AuthorizationError
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Raised when an authenticated actor is not allowed to perform a business
+ * action — the "you may not" error, distinct from authentication ("who are
+ * you"). Maps to an HTTP 403 at the edge.
+ *
+ * The discriminating {@link reason} records *why* access was denied (a flat
+ * forbid, a missing role/capability, an out-of-scope target, or a policy
+ * decision) so the boundary can shape the response without re-deriving it. The
+ * metadata is deliberately built around a stable business `action` and a
+ * type/id resource reference rather than an HTTP route or full payload, keeping
+ * sensitive data out of logs. Instances are frozen. Construct through the
+ * static factories, never directly.
+ */
 class AuthorizationError extends AppError {
     public readonly reason: AuthorizationErrorReason;
 
@@ -98,6 +111,12 @@ class AuthorizationError extends AppError {
     // Factories
     // ─────────────────────────────────────────────────────────────────────────
 
+    /**
+     * A flat denial with no more specific reason — the actor simply may not
+     * perform this action. Reach for a more precise factory
+     * ({@link AuthorizationError.missingCapability}, {@link AuthorizationError.outOfScope},
+     * {@link AuthorizationError.policyDenied}) when the cause is known.
+     */
     static forbidden(
         input: AuthorizationErrorFactoryOptions,
     ): AuthorizationError {
@@ -110,6 +129,15 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The action was denied by an evaluated policy. Captures the deciding
+     * policy's id, version, and evaluation instant into the metadata (with
+     * `decision: "deny"`) so the denial is auditable back to the exact policy
+     * that produced it.
+     *
+     * @param input - Factory options plus the required `policyId`,
+     *   `policyVersion`, and `evaluatedAtIso` of the deciding policy.
+     */
     static policyDenied(
         input: AuthorizationErrorFactoryOptions & {
             policyId: string;
@@ -130,6 +158,13 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The actor lacks a required role or capability. The expected
+     * {@link AuthorizationRequirement} is recorded so the boundary can tell the
+     * caller precisely what grant is missing.
+     *
+     * @param input - Factory options plus the `required` role/capability/scope.
+     */
     static missingCapability(
         input: AuthorizationErrorFactoryOptions & {
             required: AuthorizationRequirement;
@@ -147,6 +182,14 @@ class AuthorizationError extends AppError {
         });
     }
 
+    /**
+     * The actor may perform the action in general, but not on *this* target —
+     * the resource falls outside the actor's permitted scope (e.g. a different
+     * school or tenant than the one they are bound to).
+     *
+     * @param input - Factory options plus the optional `required` scope that the
+     *   target failed to satisfy.
+     */
     static outOfScope(
         input: AuthorizationErrorFactoryOptions & {
             required?: AuthorizationRequirement;

package/src/core/errors/conflict-error.ts

@@ -26,6 +26,11 @@ type ConflictErrorMetadata = {
     hint?: string;
 };
 
+/**
+ * Storage-level description of a unique-constraint breach, as reported by a
+ * database driver. Used to translate a raw DB error into a domain
+ * {@link DuplicateError} via {@link translateUniqueViolationToDuplicate}.
+ */
 type UniqueConstraintViolation = {
     kind: "unique_violation";
     constraintName?: string;
@@ -33,6 +38,17 @@ type UniqueConstraintViolation = {
     columns?: string[];
 };
 
+/**
+ * Base for errors that signal a state conflict — the request collides with data
+ * that already exists. Common at an HTTP 409 boundary.
+ *
+ * The discriminating {@link kind} lets a handler branch on *why* it conflicted
+ * (an already-existing record, a domain duplicate, or a raw storage uniqueness
+ * breach) without `instanceof` chains. Abstract: construct one of the concrete
+ * subclasses through its `detected(...)` factory, which fills in the right code,
+ * message, and metadata. Instances are frozen, so a conflict error can be shared
+ * and rethrown without risk of tampering.
+ */
 abstract class ConflictError extends AppError {
     public readonly kind: ConflictKind;
 
@@ -58,6 +74,11 @@ abstract class ConflictError extends AppError {
     }
 }
 
+/**
+ * The operation cannot proceed because a matching record already exists —
+ * e.g. creating something whose natural key is already taken. Construct via
+ * {@link AlreadyExistsError.detected}.
+ */
 class AlreadyExistsError extends ConflictError {
     private constructor(
         input: {
@@ -74,6 +95,14 @@ class AlreadyExistsError extends ConflictError {
         });
     }
 
+    /**
+     * Builds an {@link AlreadyExistsError} for a detected collision. `operation`
+     * defaults to `"create"` and a generic retry `hint` is supplied when none is
+     * given, so the error is actionable even from a minimal call site.
+     *
+     * @param input - The conflicting entity plus optional non-sensitive context
+     *   (operation, field, existing id, value hash/preview, correlation ids).
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -107,6 +136,13 @@ class AlreadyExistsError extends ConflictError {
     }
 }
 
+/**
+ * A domain-level duplicate: the data being written would duplicate an existing
+ * record under the model's own uniqueness rules. Use this when the duplication
+ * is recognized in the domain, as opposed to a raw DB constraint
+ * ({@link UniqueConstraintViolationError}). Construct via
+ * {@link DuplicateError.detected}.
+ */
 class DuplicateError extends ConflictError {
     private constructor(
         input: {
@@ -122,6 +158,13 @@ class DuplicateError extends ConflictError {
         });
     }
 
+    /**
+     * Builds a {@link DuplicateError} for a detected duplicate, defaulting to a
+     * "adjust the data so it does not duplicate" hint when none is provided.
+     *
+     * @param input - The conflicting entity plus optional non-sensitive context
+     *   (field, constraint name, existing id, value hash/preview, correlation ids).
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -159,6 +202,14 @@ class DuplicateError extends ConflictError {
     }
 }
 
+/**
+ * A uniqueness breach surfaced by the storage layer itself (a database unique
+ * index), carrying the raw {@link UniqueConstraintViolation} (constraint, table,
+ * columns). Keep this distinct from {@link DuplicateError}: this one is the
+ * infrastructure signal; translate it into a domain duplicate at the boundary
+ * with {@link translateUniqueViolationToDuplicate} when the model should own the
+ * message. Construct via {@link UniqueConstraintViolationError.detected}.
+ */
 class UniqueConstraintViolationError extends ConflictError {
     private constructor(
         input: {
@@ -176,6 +227,13 @@ class UniqueConstraintViolationError extends ConflictError {
         });
     }
 
+    /**
+     * Builds a {@link UniqueConstraintViolationError} from the constraint details
+     * a driver reports, packaging them into a nested `violation` payload.
+     *
+     * @param input - The entity plus the offending constraint name, table, and
+     *   columns, and optional correlation ids.
+     */
     static detected(input: {
         entity: string;
         operation?: string;
@@ -210,6 +268,17 @@ class UniqueConstraintViolationError extends ConflictError {
     }
 }
 
+/**
+ * Translates a raw storage {@link UniqueConstraintViolation} into a domain-level
+ * {@link DuplicateError}. This is the seam where an infrastructure concern (a DB
+ * unique index firing) is re-expressed in the language of the model, so callers
+ * upstream catch a `DuplicateError` and never have to know a database was
+ * involved.
+ *
+ * @param input - The entity, the driver-reported `violation`, and optional
+ *   request context (`ctx`) carrying correlation ids and a clock instant.
+ * @returns A {@link DuplicateError} carrying the constraint name as its field hint.
+ */
 function translateUniqueViolationToDuplicate(input: {
     entity: string;
     operation?: string;

package/src/core/errors/integration-error.ts

@@ -42,6 +42,18 @@ type IntegrationErrorConstructorParams = {
     metadata: IntegrationErrorMetadata;
 } & IntegrationErrorAppOptions;
 
+/**
+ * Raised when a call to an external provider fails — a timeout, an unreachable
+ * endpoint, or a malformed response. This is the boundary error that separates
+ * "our code is fine, the outside world misbehaved" from internal faults, which
+ * matters for retry and alerting decisions.
+ *
+ * Every instance records the `provider`, the `operation`, and timing
+ * (`startedAtIso` / `durationMs`) so failures are correlatable across services
+ * and a slow dependency is visible in the metadata. The discriminating
+ * {@link reason} lets callers decide whether a failure is worth retrying.
+ * Instances are frozen; construct through the static factories.
+ */
 class IntegrationError extends AppError {
     public readonly reason: IntegrationErrorReason;
 
@@ -56,6 +68,10 @@ class IntegrationError extends AppError {
         Object.freeze(this);
     }
 
+    /**
+     * The provider did not respond within the allotted time. Usually retryable,
+     * since a timeout leaves the outcome unknown rather than known-failed.
+     */
     static timeout(options: IntegrationErrorTimeoutOptions): IntegrationError {
         return new IntegrationError({
             message: "Timeout while integrating with external provider",
@@ -66,6 +82,10 @@ class IntegrationError extends AppError {
         });
     }
 
+    /**
+     * The provider could not be reached at all (connection refused, DNS
+     * failure, network partition) — the request never landed.
+     */
     static unreachable(
         options: IntegrationErrorEndpointOptions,
     ): IntegrationError {
@@ -78,6 +98,11 @@ class IntegrationError extends AppError {
         });
     }
 
+    /**
+     * The provider answered, but with something the system cannot use — an
+     * unexpected status, an unparsable body, or a contract mismatch. Unlike a
+     * timeout this is a definite failure, so blind retries rarely help.
+     */
     static badResponse(
         options: IntegrationErrorEndpointOptions,
     ): IntegrationError {

package/src/core/errors/not-found-error.ts

@@ -6,7 +6,21 @@ import type { AppErrorOptions } from "./types.js";
 // NotFoundError
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Raised when a requested resource does not exist. Maps naturally onto an HTTP
+ * 404 at the edge, but stays transport-agnostic here.
+ *
+ * The `resource` name builds the message (`"<resource> not found"`) and, with
+ * the optional lookup `criteria`, lands in the metadata so logs show *what* was
+ * searched for without the caller having to restate it in the message.
+ */
 class NotFoundError extends AppError {
+    /**
+     * @param resource - Human-readable name of the missing resource (e.g. `"Order"`).
+     * @param criteria - Optional lookup keys used in the search; recorded in
+     *   metadata to aid debugging. Avoid putting sensitive values here.
+     * @param options - Optional cause, correlation ids, and extra metadata.
+     */
     constructor(
         resource: string,
         criteria?: Record<string, unknown>,