@cullet/erp-core 1.1.0 → 1.3.0

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

@@ -1,6 +1,21 @@
+import { PluginManager } from "../plugins/index.js";
 import { type DeepReadonly, makeImmutable } from "../shared/immutable.js";
 import { type ContractVersion, version } from "../versioning/version.js";
 
+/**
+ * Extension point for value-object equality. A plugin implementing this
+ * contract overrides how any two value objects are compared, letting the host
+ * application swap in a structural comparator (e.g. `lodash.isEqual` over the
+ * wrapped `value`) without every value object having to implement `equals` by
+ * hand.
+ */
+type ValueObjectPluginContract = {
+    equals: (
+        a: ValueObject<unknown, unknown>,
+        b: ValueObject<unknown, unknown>,
+    ) => boolean;
+};
+
 /**
  * Base class for value objects — domain concepts defined entirely by their
  * contents, with no identity of their own. Two value objects are
@@ -20,6 +35,15 @@ import { type ContractVersion, version } from "../versioning/version.js";
 abstract class ValueObject<T, P> {
     declare public static readonly CONTRACT_VERSION: ContractVersion;
 
+    /**
+     * Registry of equality plugins shared by every value object. Empty by
+     * default — when nothing is registered, {@link equals} falls back to a
+     * structural comparison of the wrapped `value`. Hosts register a plugin
+     * (e.g. `lodash.isEqual`) once at startup to customise equality globally.
+     */
+    public static readonly plugins =
+        new PluginManager<ValueObjectPluginContract>();
+
     /** The wrapped data, deep-frozen so it can never be mutated after construction. */
     public readonly value: DeepReadonly<T>;
 
@@ -65,11 +89,19 @@ abstract class ValueObject<T, P> {
 
     /**
      * 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.
+     * carry no identity, two independently constructed instances holding the
+     * same data are considered equal.
+     *
+     * Delegates to the registered equality {@link plugins}; with no plugin
+     * registered it falls back to comparing the serialized wrapped `value`.
+     * Subclasses may still override for a faster or domain-specific comparison.
      */
-    public abstract equals(other: this): boolean;
+    public equals(other: this): boolean {
+        return ValueObject.plugins.invoke("equals", [this, other], {
+            fallback: (a, b) =>
+                JSON.stringify(a.value) === JSON.stringify(b.value),
+        });
+    }
 
     /**
      * Projects the value object down to a plain, serializable primitive form —
@@ -78,4 +110,4 @@ abstract class ValueObject<T, P> {
     public abstract toPrimitive(): P;
 }
 
-export { type DeepReadonly, ValueObject };
+export { type DeepReadonly, ValueObject, type ValueObjectPluginContract };

package/src/core/exceptions/index.ts

@@ -0,0 +1,13 @@
+export { BusinessRuleViolationException } from "./business-rule-violation-exception.js";
+export { DomainException } from "./domain-exception.js";
+export { EntityNotFoundException } from "./entity-not-found-exception.js";
+export { InvalidStateTransitionException } from "./invalid-state-transition-exception.js";
+export { InvariantViolationException } from "./invariant-violation-exception.js";
+export { ValidationCode } from "./validation-code.js";
+export {
+    InvalidValueException,
+    MultipleValidationException,
+    ValidationException,
+    type ValidationViolation,
+} from "./validation-exception.js";
+export { ValidationField } from "./validation-field.js";

package/src/core/index.ts

@@ -1,6 +1,18 @@
 export * from "./errors/index.js";
-export * from "./exceptions/validation-field.js";
+export * from "./exceptions/index.js";
 export * from "./application/index.js";
 export { Entity, type EntityState } from "./domain/entity.js";
-export { ValueObject, type DeepReadonly } from "./domain/value-object.js";
+export { UuidIdentifier } from "./domain/uuid-identifier.js";
+export {
+    ValueObject,
+    type DeepReadonly,
+    type ValueObjectPluginContract,
+} from "./domain/value-object.js";
+export * from "./domain/rulesets/index.js";
+export * from "./plugins/index.js";
+export * from "./versioning/index.js";
+// NOTE: `./policies` re-exports Result/Ok/Err/Outcome/CommonOutcomeStatus and
+// transitively pulls in `zod` (the gate/compute engines). Consumers that only
+// need the zod-free primitives should import the dedicated subpaths
+// (`@cullet/erp-core/{domain,result,exceptions,rulesets,versioning,plugins}`).
 export * from "./policies/index.js";

package/src/core/plugins/index.ts

@@ -0,0 +1,7 @@
+export { PluginManager } from "./plugin.js";
+export type {
+    BasePlugin,
+    InvokeOptions,
+    PipelineReducer,
+    PluginContract,
+} from "./types.js";

package/src/core/plugins/plugin.ts

@@ -0,0 +1,99 @@
+import {
+    type BasePlugin,
+    type InvokeOptions,
+    type PipelineReducer,
+    type PluginContract,
+} from "./types.js";
+
+/**
+ * Registry that holds a set of plugins implementing a shared {@link PluginContract}
+ * and resolves which of them answer a given extension point.
+ *
+ * Plugins are kept sorted by priority (descending). For a given method,
+ * {@link invoke} either delegates to the highest-priority enabled plugin
+ * (`'first'`) or folds every enabled plugin into a single value (`'pipeline'`).
+ * When no plugin is enabled, the supplied `fallback` runs instead, so the host
+ * always has defined behaviour even with an empty registry.
+ *
+ * @typeParam P - The plugin contract this manager coordinates.
+ */
+class PluginManager<P extends PluginContract> {
+    /** Internal list, kept sorted by priority (desc). */
+    private plugins: (P & BasePlugin)[] = [];
+
+    /** Registers one or more plugins and re-sorts by priority. */
+    public register(...plugins: (P & BasePlugin)[]): void {
+        this.plugins.push(...plugins);
+        this.reorder();
+    }
+
+    /** Removes a previously registered plugin by name. */
+    public unregister(name: string): void {
+        this.plugins = this.plugins.filter((p) => p.name !== name);
+    }
+
+    /** Enables a registered plugin by name. */
+    public enable(name: string): void {
+        const plugin = this.plugins.find((p) => p.name === name);
+        if (plugin) plugin.enabled = true;
+    }
+
+    /** Disables a registered plugin by name (without removing it). */
+    public disable(name: string): void {
+        const plugin = this.plugins.find((p) => p.name === name);
+        if (plugin) plugin.enabled = false;
+    }
+
+    /** Lists enabled plugins only, already in priority order. */
+    public list(): readonly (P & BasePlugin)[] {
+        return this.plugins.filter((p) => p.enabled !== false);
+    }
+
+    /**
+     * Resolves `method` against the registered plugins.
+     *
+     * In `'first'` mode the highest-priority enabled plugin that implements
+     * `method` answers. In `'pipeline'` mode every enabled plugin runs and the
+     * results are folded with `reducer` (defaults to "keep the last result").
+     * When no enabled plugin implements `method`, `fallback` is called.
+     */
+    public invoke<K extends keyof P>(
+        method: K,
+        args: Parameters<P[K]>,
+        opts: InvokeOptions<P, K>,
+    ): ReturnType<P[K]> {
+        const { mode = "first", fallback, reducer } = opts;
+        const enabled = this.list().filter((p) => method in p) as Array<
+            P & BasePlugin
+        >;
+
+        if (enabled.length === 0) {
+            return (fallback as P[K])(...args);
+        }
+
+        if (mode === "first") {
+            const fn = enabled[0][method] as P[K];
+            return fn(...args);
+        }
+
+        const defaultReducer: PipelineReducer<ReturnType<P[K]>, P> = (
+            _,
+            curr,
+        ) => curr;
+        const red = reducer ?? defaultReducer;
+
+        let acc: ReturnType<P[K]> = enabled[0][method]!(...args);
+        enabled.slice(1).forEach((plugin, idx) => {
+            const res = plugin[method]!(...args);
+            acc = red(acc, res, plugin, idx + 1);
+        });
+        return acc;
+    }
+
+    /** Re-sorts the internal list by priority (desc; default priority = 0). */
+    private reorder(): void {
+        this.plugins.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    }
+}
+
+export { PluginManager };

package/src/core/plugins/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Common shape every plugin shares, regardless of the contract it implements.
+ * Carries the metadata the {@link PluginManager} uses to identify, order and
+ * toggle plugins.
+ */
+interface BasePlugin {
+    /** Unique identifier, used for logs / debugging and for enable/disable. */
+    readonly name: string;
+    /** Weight; the highest priority wins (default = 0). */
+    readonly priority?: number;
+    /** Shortcut to disable a plugin without removing it. */
+    enabled?: boolean;
+}
+
+/**
+ * A plugin contract is a record whose values are the methods plugins may
+ * implement for a given extension point.
+ *
+ * `any` here is intentional: it is the only way to express the constraint
+ * "a record whose values are arbitrary functions". Using `unknown` for the
+ * parameters breaks assignment of concrete contracts by contravariance —
+ * TypeScript rejects functions with specific parameters as a subtype of
+ * `(...args: unknown[]) => unknown`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PluginContract = Record<string, (...args: any[]) => any>;
+
+/**
+ * Reducer used in `pipeline` mode to combine the result of each plugin into a
+ * single accumulated value.
+ */
+type PipelineReducer<R, P extends PluginContract> = (
+    accumulated: R,
+    current: R,
+    plugin: P & BasePlugin,
+    index: number,
+) => R;
+
+/** Options accepted by {@link PluginManager.invoke}. */
+interface InvokeOptions<P extends PluginContract, K extends keyof P> {
+    /**
+     * `'first'`    → returns the first enabled plugin with the highest priority.
+     * `'pipeline'` → runs every enabled plugin, combining results via `reducer`.
+     * default = `'first'`.
+     */
+    mode?: "first" | "pipeline";
+    /** Executed when no plugin is enabled for the method. */
+    fallback: P[K];
+    /** Reducer used only when `mode = "pipeline"`. */
+    reducer?: PipelineReducer<ReturnType<P[K]>, P>;
+}
+
+export type { BasePlugin, InvokeOptions, PipelineReducer, PluginContract };

package/src/core/versioning/index.ts

@@ -0,0 +1,14 @@
+export {
+    buildDomainEventContractVersions,
+    createDomainEventEnvelope,
+    type CreateDomainEventEnvelopeInput,
+    type DomainEventContractSelection,
+    type DomainEventContractVersions,
+    type DomainEventEnvelope,
+} from "./domain-event-contracts.js";
+export {
+    CONTRACT_VERSION_PROPERTY,
+    type ContractVersion,
+    version,
+    type VersionedTarget,
+} from "./version.js";

package/src/domain/index.ts

@@ -0,0 +1,7 @@
+export { Entity, type EntityState } from "../core/domain/entity.js";
+export { UuidIdentifier } from "../core/domain/uuid-identifier.js";
+export {
+    type DeepReadonly,
+    ValueObject,
+    type ValueObjectPluginContract,
+} from "../core/domain/value-object.js";

package/src/exceptions/index.ts

@@ -0,0 +1 @@
+export * from "../core/exceptions/index.js";

package/src/plugins/index.ts

@@ -0,0 +1 @@
+export * from "../core/plugins/index.js";

package/src/result/index.ts

@@ -0,0 +1,2 @@
+export { type CommonOutcomeStatus, Outcome } from "../core/result/outcome.js";
+export { Err, Ok, Result } from "../core/result/result.js";

package/src/rulesets/index.ts

@@ -0,0 +1 @@
+export * from "../core/domain/rulesets/index.js";

package/src/version.ts

@@ -4,4 +4,4 @@
 // Mantemos a versao aqui, dentro de src/, para que a copia full-control seja
 // auto-contida: ao copiar so o conteudo de src/, o entry nao depende de um
 // `../package.json` que deixaria de existir no projeto consumidor.
-export const version = "1.1.0";
+export const version = "1.3.0";

package/src/versioning/index.ts

@@ -0,0 +1 @@
+export * from "../core/versioning/index.js";