@happyvertical/smrt-core 0.30.0

package/dist/interceptors.d.ts

@@ -0,0 +1,251 @@
+import { SmrtObject } from './object.js';
+/**
+ * Context passed to interceptors with operation metadata
+ */
+export interface InterceptorContext {
+    /** Name of the SMRT class being operated on */
+    className: string;
+    /** Name of the collection (if applicable) */
+    collectionName?: string;
+    /** Timestamp of the operation */
+    timestamp: Date;
+    /** Operation type for debugging */
+    operation: 'list' | 'get' | 'query' | 'save' | 'delete';
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for list operations
+ */
+export interface ListOptions {
+    where?: Record<string, unknown>;
+    orderBy?: string | string[];
+    limit?: number;
+    offset?: number;
+    include?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Options for query operations (raw SQL)
+ */
+export interface QueryOptions {
+    /** The raw SQL query */
+    sql: string;
+    /** Query parameters */
+    params: unknown[];
+    /** If true, allow raw SQL on tenant-scoped classes (requires explicit opt-in) */
+    allowRawOnTenantScoped?: boolean;
+}
+/**
+ * Result from query interceptor - can modify SQL or throw to block
+ */
+export interface QueryInterceptResult {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Interface for collection/object interceptors
+ *
+ * All methods are optional. Return void to pass through unchanged,
+ * or return modified data to transform the operation.
+ */
+export interface CollectionInterceptor {
+    /** Unique identifier for this interceptor (for debugging/unregistration) */
+    name?: string;
+    /** Priority for execution order (higher = earlier). Default: 0 */
+    priority?: number;
+    /**
+     * Called before list() operations
+     * @param className - Name of the class being listed
+     * @param options - List options (where, orderBy, limit, etc.)
+     * @param context - Operation context
+     * @returns Modified options or void to pass through
+     */
+    beforeList?(className: string, options: ListOptions, context: InterceptorContext): ListOptions | Promise<ListOptions> | void | Promise<void>;
+    /**
+     * Called after list() operations with results
+     * @param className - Name of the class
+     * @param results - Array of hydrated instances
+     * @param context - Operation context
+     * @returns Modified results or void to pass through
+     */
+    afterList?<T extends SmrtObject>(className: string, results: T[], context: InterceptorContext): T[] | Promise<T[]> | void | Promise<void>;
+    /**
+     * Called before get() operations
+     * @param className - Name of the class
+     * @param filter - ID, slug, or filter object
+     * @param context - Operation context
+     * @returns Modified filter or void to pass through
+     */
+    beforeGet?(className: string, filter: string | Record<string, unknown>, context: InterceptorContext): string | Record<string, unknown> | Promise<string | Record<string, unknown>> | void | Promise<void>;
+    /**
+     * Called after get() operations with result
+     * @param className - Name of the class
+     * @param instance - Hydrated instance or null if not found
+     * @param context - Operation context
+     * @returns Modified instance, null, or void to pass through
+     */
+    afterGet?<T extends SmrtObject>(className: string, instance: T | null, context: InterceptorContext): T | null | Promise<T | null> | void | Promise<void>;
+    /**
+     * Called before query() operations (raw SQL)
+     * @param className - Name of the class
+     * @param options - Query options with SQL and params
+     * @param context - Operation context
+     * @returns Modified query options, or throw to block the query
+     */
+    beforeQuery?(className: string, options: QueryOptions, context: InterceptorContext): QueryInterceptResult | Promise<QueryInterceptResult> | void | Promise<void>;
+    /**
+     * Called after query() operations with results
+     * @param className - Name of the class
+     * @param results - Array of hydrated instances
+     * @param context - Operation context
+     * @returns Modified results or void to pass through
+     */
+    afterQuery?<T extends SmrtObject>(className: string, results: T[], context: InterceptorContext): T[] | Promise<T[]> | void | Promise<void>;
+    /**
+     * Called before save() operations
+     * @param instance - The object being saved
+     * @param context - Operation context
+     * @returns void (modify instance in place) or throw to block
+     */
+    beforeSave?(instance: SmrtObject, context: InterceptorContext): void | Promise<void>;
+    /**
+     * Called after save() operations
+     * @param instance - The saved object
+     * @param context - Operation context
+     */
+    afterSave?(instance: SmrtObject, context: InterceptorContext): void | Promise<void>;
+    /**
+     * Called before delete() operations
+     * @param instance - The object being deleted
+     * @param context - Operation context
+     * @returns void or throw to block
+     */
+    beforeDelete?(instance: SmrtObject, context: InterceptorContext): void | Promise<void>;
+    /**
+     * Called after delete() operations
+     * @param instance - The deleted object
+     * @param context - Operation context
+     */
+    afterDelete?(instance: SmrtObject, context: InterceptorContext): void | Promise<void>;
+}
+/**
+ * Extend globalThis to include interceptors state.
+ * Using globalThis ensures all module instances share the same interceptors,
+ * which is critical in monorepos where the same package can be loaded
+ * from different paths.
+ *
+ * @see ObjectRegistry for similar pattern
+ */
+declare global {
+    var __smrtInterceptors: unknown[] | undefined;
+}
+/**
+ * Global Interceptors Registry
+ *
+ * Manages collection/object interceptors for the SMRT framework.
+ * External packages can register interceptors to hook into operations
+ * without modifying core code.
+ */
+export declare class GlobalInterceptors {
+    /**
+     * Get the global interceptors array (lazy-initialized)
+     */
+    private static get interceptors();
+    /**
+     * Register an interceptor
+     *
+     * @param interceptor - The interceptor to register
+     * @example
+     * ```typescript
+     * GlobalInterceptors.register({
+     *   name: 'tenancy',
+     *   priority: 100,
+     *   beforeList(className, options) {
+     *     // Add tenant filtering
+     *     return { ...options, where: { ...options.where, tenantId: 'xxx' } };
+     *   }
+     * });
+     * ```
+     */
+    static register(interceptor: CollectionInterceptor): void;
+    /**
+     * Unregister an interceptor by reference or name
+     *
+     * @param interceptorOrName - The interceptor instance or name to remove
+     * @returns true if removed, false if not found
+     */
+    static unregister(interceptorOrName: CollectionInterceptor | string): boolean;
+    /**
+     * Clear all interceptors (useful for testing)
+     */
+    static clear(): void;
+    /**
+     * Get all registered interceptors (readonly)
+     */
+    static getAll(): readonly CollectionInterceptor[];
+    /**
+     * Check if any interceptors are registered
+     */
+    static hasInterceptors(): boolean;
+    /**
+     * Sort interceptors by priority (higher priority first)
+     */
+    private static sortByPriority;
+    /**
+     * Execute beforeList interceptors
+     * @internal Called by SmrtCollection.list()
+     */
+    static executeBeforeList(className: string, options: ListOptions, context: InterceptorContext): Promise<ListOptions>;
+    /**
+     * Execute afterList interceptors
+     * @internal Called by SmrtCollection.list()
+     */
+    static executeAfterList<T extends SmrtObject>(className: string, results: T[], context: InterceptorContext): Promise<T[]>;
+    /**
+     * Execute beforeGet interceptors
+     * @internal Called by SmrtCollection.get()
+     */
+    static executeBeforeGet(className: string, filter: string | Record<string, unknown>, context: InterceptorContext): Promise<string | Record<string, unknown>>;
+    /**
+     * Execute afterGet interceptors
+     * @internal Called by SmrtCollection.get()
+     */
+    static executeAfterGet<T extends SmrtObject>(className: string, instance: T | null, context: InterceptorContext): Promise<T | null>;
+    /**
+     * Execute beforeQuery interceptors
+     * @internal Called by SmrtCollection.query()
+     */
+    static executeBeforeQuery(className: string, options: QueryOptions, context: InterceptorContext): Promise<QueryInterceptResult>;
+    /**
+     * Execute afterQuery interceptors
+     * @internal Called by SmrtCollection.query()
+     */
+    static executeAfterQuery<T extends SmrtObject>(className: string, results: T[], context: InterceptorContext): Promise<T[]>;
+    /**
+     * Execute beforeSave interceptors
+     * @internal Called by SmrtObject.save()
+     */
+    static executeBeforeSave(instance: SmrtObject, context: InterceptorContext): Promise<void>;
+    /**
+     * Execute afterSave interceptors
+     * @internal Called by SmrtObject.save()
+     */
+    static executeAfterSave(instance: SmrtObject, context: InterceptorContext): Promise<void>;
+    /**
+     * Execute beforeDelete interceptors
+     * @internal Called by SmrtObject.delete()
+     */
+    static executeBeforeDelete(instance: SmrtObject, context: InterceptorContext): Promise<void>;
+    /**
+     * Execute afterDelete interceptors
+     * @internal Called by SmrtObject.delete()
+     */
+    static executeAfterDelete(instance: SmrtObject, context: InterceptorContext): Promise<void>;
+}
+/**
+ * Helper function to create an interceptor context
+ * @internal
+ */
+export declare function createInterceptorContext(className: string, operation: InterceptorContext['operation'], collectionName?: string, metadata?: Record<string, unknown>): InterceptorContext;
+//# sourceMappingURL=interceptors.d.ts.map

package/dist/interceptors.d.ts.map

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

package/dist/interceptors.js

@@ -0,0 +1,259 @@
+class GlobalInterceptors {
+  /**
+   * Get the global interceptors array (lazy-initialized)
+   */
+  static get interceptors() {
+    if (!globalThis.__smrtInterceptors) {
+      globalThis.__smrtInterceptors = [];
+    }
+    return globalThis.__smrtInterceptors;
+  }
+  /**
+   * Register an interceptor
+   *
+   * @param interceptor - The interceptor to register
+   * @example
+   * ```typescript
+   * GlobalInterceptors.register({
+   *   name: 'tenancy',
+   *   priority: 100,
+   *   beforeList(className, options) {
+   *     // Add tenant filtering
+   *     return { ...options, where: { ...options.where, tenantId: 'xxx' } };
+   *   }
+   * });
+   * ```
+   */
+  static register(interceptor) {
+    if (interceptor.name) {
+      const existing = this.interceptors.findIndex(
+        (i) => i.name === interceptor.name
+      );
+      if (existing >= 0) {
+        this.interceptors[existing] = interceptor;
+        this.sortByPriority();
+        return;
+      }
+    }
+    this.interceptors.push(interceptor);
+    this.sortByPriority();
+  }
+  /**
+   * Unregister an interceptor by reference or name
+   *
+   * @param interceptorOrName - The interceptor instance or name to remove
+   * @returns true if removed, false if not found
+   */
+  static unregister(interceptorOrName) {
+    const idx = typeof interceptorOrName === "string" ? this.interceptors.findIndex((i) => i.name === interceptorOrName) : this.interceptors.indexOf(interceptorOrName);
+    if (idx >= 0) {
+      this.interceptors.splice(idx, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Clear all interceptors (useful for testing)
+   */
+  static clear() {
+    globalThis.__smrtInterceptors = [];
+  }
+  /**
+   * Get all registered interceptors (readonly)
+   */
+  static getAll() {
+    return [...this.interceptors];
+  }
+  /**
+   * Check if any interceptors are registered
+   */
+  static hasInterceptors() {
+    return this.interceptors.length > 0;
+  }
+  /**
+   * Sort interceptors by priority (higher priority first)
+   */
+  static sortByPriority() {
+    this.interceptors.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Execution methods - called by SmrtCollection and SmrtObject
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Execute beforeList interceptors
+   * @internal Called by SmrtCollection.list()
+   */
+  static async executeBeforeList(className, options, context) {
+    let result = options;
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeList) {
+        const modified = await interceptor.beforeList(
+          className,
+          result,
+          context
+        );
+        if (modified !== void 0 && modified !== null) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute afterList interceptors
+   * @internal Called by SmrtCollection.list()
+   */
+  static async executeAfterList(className, results, context) {
+    let result = results;
+    for (const interceptor of this.interceptors) {
+      if (interceptor.afterList) {
+        const modified = await interceptor.afterList(
+          className,
+          result,
+          context
+        );
+        if (modified !== void 0 && modified !== null) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute beforeGet interceptors
+   * @internal Called by SmrtCollection.get()
+   */
+  static async executeBeforeGet(className, filter, context) {
+    let result = filter;
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeGet) {
+        const modified = await interceptor.beforeGet(
+          className,
+          result,
+          context
+        );
+        if (modified !== void 0 && modified !== null) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute afterGet interceptors
+   * @internal Called by SmrtCollection.get()
+   */
+  static async executeAfterGet(className, instance, context) {
+    let result = instance;
+    for (const interceptor of this.interceptors) {
+      if (interceptor.afterGet) {
+        const modified = await interceptor.afterGet(className, result, context);
+        if (modified !== void 0) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute beforeQuery interceptors
+   * @internal Called by SmrtCollection.query()
+   */
+  static async executeBeforeQuery(className, options, context) {
+    let result = {
+      sql: options.sql,
+      params: options.params
+    };
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeQuery) {
+        const modified = await interceptor.beforeQuery(
+          className,
+          { ...options, ...result },
+          context
+        );
+        if (modified !== void 0 && modified !== null) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute afterQuery interceptors
+   * @internal Called by SmrtCollection.query()
+   */
+  static async executeAfterQuery(className, results, context) {
+    let result = results;
+    for (const interceptor of this.interceptors) {
+      if (interceptor.afterQuery) {
+        const modified = await interceptor.afterQuery(
+          className,
+          result,
+          context
+        );
+        if (modified !== void 0 && modified !== null) {
+          result = modified;
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute beforeSave interceptors
+   * @internal Called by SmrtObject.save()
+   */
+  static async executeBeforeSave(instance, context) {
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeSave) {
+        await interceptor.beforeSave(instance, context);
+      }
+    }
+  }
+  /**
+   * Execute afterSave interceptors
+   * @internal Called by SmrtObject.save()
+   */
+  static async executeAfterSave(instance, context) {
+    for (const interceptor of this.interceptors) {
+      if (interceptor.afterSave) {
+        await interceptor.afterSave(instance, context);
+      }
+    }
+  }
+  /**
+   * Execute beforeDelete interceptors
+   * @internal Called by SmrtObject.delete()
+   */
+  static async executeBeforeDelete(instance, context) {
+    for (const interceptor of this.interceptors) {
+      if (interceptor.beforeDelete) {
+        await interceptor.beforeDelete(instance, context);
+      }
+    }
+  }
+  /**
+   * Execute afterDelete interceptors
+   * @internal Called by SmrtObject.delete()
+   */
+  static async executeAfterDelete(instance, context) {
+    for (const interceptor of this.interceptors) {
+      if (interceptor.afterDelete) {
+        await interceptor.afterDelete(instance, context);
+      }
+    }
+  }
+}
+function createInterceptorContext(className, operation, collectionName, metadata) {
+  return {
+    className,
+    collectionName,
+    operation,
+    timestamp: /* @__PURE__ */ new Date(),
+    metadata
+  };
+}
+export {
+  GlobalInterceptors,
+  createInterceptorContext
+};
+//# sourceMappingURL=interceptors.js.map

package/dist/interceptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.js","sources":["../src/interceptors.ts"],"sourcesContent":["/**\n * Global Interceptors System for SMRT Collections and Objects\n *\n * Provides a plugin architecture for intercepting collection and object operations.\n * This enables external packages (like @happyvertical/smrt-tenancy) to register\n * interceptors without creating circular dependencies.\n *\n * Pattern: Static methods on GlobalInterceptors class with globalThis state\n * (matches ObjectRegistry pattern for cross-module state sharing)\n *\n * @example Basic interceptor registration\n * ```typescript\n * import { GlobalInterceptors } from '@happyvertical/smrt-core';\n *\n * // Register a beforeList interceptor\n * GlobalInterceptors.register({\n *   beforeList(className, options) {\n *     console.log(`Listing ${className}`);\n *     return options; // Return modified options\n *   }\n * });\n * ```\n *\n * @example Tenancy interceptor (from smrt-tenancy)\n * ```typescript\n * GlobalInterceptors.register({\n *   beforeList(className, options, context) {\n *     const tenantId = getCurrentTenantId();\n *     if (tenantId && isTenantScoped(className)) {\n *       return {\n *         ...options,\n *         where: { ...options.where, tenantId }\n *       };\n *     }\n *     return options;\n *   },\n *   beforeSave(instance, context) {\n *     // Validate tenant on save\n *   }\n * });\n * ```\n *\n * @see https://github.com/happyvertical/smrt/issues/675\n */\n\nimport type { SmrtObject } from './object.js';\n\n/**\n * Context passed to interceptors with operation metadata\n */\nexport interface InterceptorContext {\n  /** Name of the SMRT class being operated on */\n  className: string;\n  /** Name of the collection (if applicable) */\n  collectionName?: string;\n  /** Timestamp of the operation */\n  timestamp: Date;\n  /** Operation type for debugging */\n  operation: 'list' | 'get' | 'query' | 'save' | 'delete';\n  /** Additional metadata */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Options for list operations\n */\nexport interface ListOptions {\n  where?: Record<string, unknown>;\n  orderBy?: string | string[];\n  limit?: number;\n  offset?: number;\n  include?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Options for query operations (raw SQL)\n */\nexport interface QueryOptions {\n  /** The raw SQL query */\n  sql: string;\n  /** Query parameters */\n  params: unknown[];\n  /** If true, allow raw SQL on tenant-scoped classes (requires explicit opt-in) */\n  allowRawOnTenantScoped?: boolean;\n}\n\n/**\n * Result from query interceptor - can modify SQL or throw to block\n */\nexport interface QueryInterceptResult {\n  sql: string;\n  params: unknown[];\n}\n\n/**\n * Interface for collection/object interceptors\n *\n * All methods are optional. Return void to pass through unchanged,\n * or return modified data to transform the operation.\n */\nexport interface CollectionInterceptor {\n  /** Unique identifier for this interceptor (for debugging/unregistration) */\n  name?: string;\n\n  /** Priority for execution order (higher = earlier). Default: 0 */\n  priority?: number;\n\n  /**\n   * Called before list() operations\n   * @param className - Name of the class being listed\n   * @param options - List options (where, orderBy, limit, etc.)\n   * @param context - Operation context\n   * @returns Modified options or void to pass through\n   */\n  beforeList?(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): ListOptions | Promise<ListOptions> | void | Promise<void>;\n\n  /**\n   * Called after list() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterList?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before get() operations\n   * @param className - Name of the class\n   * @param filter - ID, slug, or filter object\n   * @param context - Operation context\n   * @returns Modified filter or void to pass through\n   */\n  beforeGet?(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ):\n    | string\n    | Record<string, unknown>\n    | Promise<string | Record<string, unknown>>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after get() operations with result\n   * @param className - Name of the class\n   * @param instance - Hydrated instance or null if not found\n   * @param context - Operation context\n   * @returns Modified instance, null, or void to pass through\n   */\n  afterGet?<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): T | null | Promise<T | null> | void | Promise<void>;\n\n  /**\n   * Called before query() operations (raw SQL)\n   * @param className - Name of the class\n   * @param options - Query options with SQL and params\n   * @param context - Operation context\n   * @returns Modified query options, or throw to block the query\n   */\n  beforeQuery?(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ):\n    | QueryInterceptResult\n    | Promise<QueryInterceptResult>\n    | void\n    | Promise<void>;\n\n  /**\n   * Called after query() operations with results\n   * @param className - Name of the class\n   * @param results - Array of hydrated instances\n   * @param context - Operation context\n   * @returns Modified results or void to pass through\n   */\n  afterQuery?<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): T[] | Promise<T[]> | void | Promise<void>;\n\n  /**\n   * Called before save() operations\n   * @param instance - The object being saved\n   * @param context - Operation context\n   * @returns void (modify instance in place) or throw to block\n   */\n  beforeSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after save() operations\n   * @param instance - The saved object\n   * @param context - Operation context\n   */\n  afterSave?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called before delete() operations\n   * @param instance - The object being deleted\n   * @param context - Operation context\n   * @returns void or throw to block\n   */\n  beforeDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n\n  /**\n   * Called after delete() operations\n   * @param instance - The deleted object\n   * @param context - Operation context\n   */\n  afterDelete?(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): void | Promise<void>;\n}\n\n/**\n * Extend globalThis to include interceptors state.\n * Using globalThis ensures all module instances share the same interceptors,\n * which is critical in monorepos where the same package can be loaded\n * from different paths.\n *\n * @see ObjectRegistry for similar pattern\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtInterceptors: unknown[] | undefined;\n}\n\n/**\n * Global Interceptors Registry\n *\n * Manages collection/object interceptors for the SMRT framework.\n * External packages can register interceptors to hook into operations\n * without modifying core code.\n */\nexport class GlobalInterceptors {\n  /**\n   * Get the global interceptors array (lazy-initialized)\n   */\n  private static get interceptors(): CollectionInterceptor[] {\n    if (!globalThis.__smrtInterceptors) {\n      globalThis.__smrtInterceptors = [];\n    }\n    return globalThis.__smrtInterceptors as CollectionInterceptor[];\n  }\n\n  /**\n   * Register an interceptor\n   *\n   * @param interceptor - The interceptor to register\n   * @example\n   * ```typescript\n   * GlobalInterceptors.register({\n   *   name: 'tenancy',\n   *   priority: 100,\n   *   beforeList(className, options) {\n   *     // Add tenant filtering\n   *     return { ...options, where: { ...options.where, tenantId: 'xxx' } };\n   *   }\n   * });\n   * ```\n   */\n  static register(interceptor: CollectionInterceptor): void {\n    // Check for duplicate by name\n    if (interceptor.name) {\n      const existing = this.interceptors.findIndex(\n        (i) => i.name === interceptor.name,\n      );\n      if (existing >= 0) {\n        // Replace existing interceptor with same name\n        this.interceptors[existing] = interceptor;\n        this.sortByPriority();\n        return;\n      }\n    }\n\n    this.interceptors.push(interceptor);\n    this.sortByPriority();\n  }\n\n  /**\n   * Unregister an interceptor by reference or name\n   *\n   * @param interceptorOrName - The interceptor instance or name to remove\n   * @returns true if removed, false if not found\n   */\n  static unregister(\n    interceptorOrName: CollectionInterceptor | string,\n  ): boolean {\n    const idx =\n      typeof interceptorOrName === 'string'\n        ? this.interceptors.findIndex((i) => i.name === interceptorOrName)\n        : this.interceptors.indexOf(interceptorOrName);\n\n    if (idx >= 0) {\n      this.interceptors.splice(idx, 1);\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Clear all interceptors (useful for testing)\n   */\n  static clear(): void {\n    globalThis.__smrtInterceptors = [];\n  }\n\n  /**\n   * Get all registered interceptors (readonly)\n   */\n  static getAll(): readonly CollectionInterceptor[] {\n    return [...this.interceptors];\n  }\n\n  /**\n   * Check if any interceptors are registered\n   */\n  static hasInterceptors(): boolean {\n    return this.interceptors.length > 0;\n  }\n\n  /**\n   * Sort interceptors by priority (higher priority first)\n   */\n  private static sortByPriority(): void {\n    this.interceptors.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));\n  }\n\n  // ─────────────────────────────────────────────────────────────────────────\n  // Execution methods - called by SmrtCollection and SmrtObject\n  // ─────────────────────────────────────────────────────────────────────────\n\n  /**\n   * Execute beforeList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeBeforeList(\n    className: string,\n    options: ListOptions,\n    context: InterceptorContext,\n  ): Promise<ListOptions> {\n    let result = options;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeList) {\n        const modified = await interceptor.beforeList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterList interceptors\n   * @internal Called by SmrtCollection.list()\n   */\n  static async executeAfterList<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterList) {\n        const modified = await interceptor.afterList(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeBeforeGet(\n    className: string,\n    filter: string | Record<string, unknown>,\n    context: InterceptorContext,\n  ): Promise<string | Record<string, unknown>> {\n    let result = filter;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeGet) {\n        const modified = await interceptor.beforeGet(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterGet interceptors\n   * @internal Called by SmrtCollection.get()\n   */\n  static async executeAfterGet<T extends SmrtObject>(\n    className: string,\n    instance: T | null,\n    context: InterceptorContext,\n  ): Promise<T | null> {\n    let result = instance;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterGet) {\n        const modified = await interceptor.afterGet(className, result, context);\n        if (modified !== undefined) {\n          result = modified as T | null;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeBeforeQuery(\n    className: string,\n    options: QueryOptions,\n    context: InterceptorContext,\n  ): Promise<QueryInterceptResult> {\n    let result: QueryInterceptResult = {\n      sql: options.sql,\n      params: options.params,\n    };\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeQuery) {\n        const modified = await interceptor.beforeQuery(\n          className,\n          { ...options, ...result },\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute afterQuery interceptors\n   * @internal Called by SmrtCollection.query()\n   */\n  static async executeAfterQuery<T extends SmrtObject>(\n    className: string,\n    results: T[],\n    context: InterceptorContext,\n  ): Promise<T[]> {\n    let result = results;\n\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterQuery) {\n        const modified = await interceptor.afterQuery(\n          className,\n          result,\n          context,\n        );\n        if (modified !== undefined && modified !== null) {\n          result = modified as T[];\n        }\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Execute beforeSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeBeforeSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeSave) {\n        await interceptor.beforeSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterSave interceptors\n   * @internal Called by SmrtObject.save()\n   */\n  static async executeAfterSave(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterSave) {\n        await interceptor.afterSave(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute beforeDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeBeforeDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.beforeDelete) {\n        await interceptor.beforeDelete(instance, context);\n      }\n    }\n  }\n\n  /**\n   * Execute afterDelete interceptors\n   * @internal Called by SmrtObject.delete()\n   */\n  static async executeAfterDelete(\n    instance: SmrtObject,\n    context: InterceptorContext,\n  ): Promise<void> {\n    for (const interceptor of this.interceptors) {\n      if (interceptor.afterDelete) {\n        await interceptor.afterDelete(instance, context);\n      }\n    }\n  }\n}\n\n/**\n * Helper function to create an interceptor context\n * @internal\n */\nexport function createInterceptorContext(\n  className: string,\n  operation: InterceptorContext['operation'],\n  collectionName?: string,\n  metadata?: Record<string, unknown>,\n): InterceptorContext {\n  return {\n    className,\n    collectionName,\n    operation,\n    timestamp: new Date(),\n    metadata,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/junction.d.ts

@@ -0,0 +1,99 @@
+import { SmrtCollection } from './collection';
+import { SmrtObject } from './object';
+/**
+ * Options passed to `attach` / `setLinks` — written into the created junction row.
+ *
+ * Common keys: `relationship`, `role`, `sortOrder`, `tenantId`.
+ * Subclass-specific keys (e.g. `placement`, `groupId` on EventParticipant) pass through.
+ * Keys must match actual camelCase column names on the junction model; unknown
+ * keys are rejected by `SmrtCollection.create`'s WHERE/field validation.
+ */
+export type JunctionAttachOptions = Record<string, unknown>;
+/**
+ * Options passed to `byLeft` / `byRight` / `detach` — additional WHERE filters
+ * narrowing the operation. Keys must match camelCase column names.
+ */
+export type JunctionFilterOptions = Record<string, unknown>;
+export declare abstract class SmrtJunction<TItem extends SmrtObject> extends SmrtCollection<TItem> {
+    /**
+     * Internal marker used by `SmrtCollection.create` to detect that this
+     * subclass is a junction and apply a registration-presence guard. Static
+     * property is inherited by all subclasses via the constructor chain.
+     * Don't rename or remove without also updating the guard.
+     */
+    static readonly _isJunctionBase: true;
+    /** Field name (camelCase) holding the "left" foreign key, e.g. `'contentId'`. */
+    protected abstract leftField: string;
+    /** Field name (camelCase) holding the "right" foreign key, e.g. `'assetId'`. */
+    protected abstract rightField: string;
+    /**
+     * Field name (camelCase) used to ORDER BY when calling `byLeft` / `byRight`.
+     * Defaults to `'sortOrder'`. Set to `null` to omit ORDER BY entirely.
+     *
+     * Independent from `positionField` — `sortField` is a *query* concern
+     * (how rows are ordered when read), while `positionField` is a *write*
+     * concern (what column `setLinks` auto-assigns to). Tables that order
+     * by a non-position field (e.g. `'createdAt'`) should set `sortField`
+     * accordingly and leave `positionField` set to `null` or its dedicated
+     * position column name.
+     */
+    protected sortField: string | null;
+    /**
+     * Field name (camelCase) that `setLinks` auto-assigns the array index
+     * to when the caller doesn't supply a value. Defaults to `'sortOrder'`.
+     * Set to `null` for tables without a dedicated position column (e.g.
+     * pure-key junctions, or tables ordered by timestamps).
+     *
+     * Writing the array index into a non-position field — like `createdAt`
+     * or `placement` — would corrupt data. Subclasses without a numeric
+     * position column MUST set this to `null`.
+     */
+    protected positionField: string | null;
+    /**
+     * Return junction rows where the left FK matches `leftId`, narrowed by
+     * optional additional WHERE filters. Ordered ASC by `sortField` if set.
+     */
+    byLeft(leftId: string, opts?: JunctionFilterOptions): Promise<TItem[]>;
+    /**
+     * Return junction rows where the right FK matches `rightId`, narrowed by
+     * optional additional WHERE filters. Ordered ASC by `sortField` if set.
+     */
+    byRight(rightId: string, opts?: JunctionFilterOptions): Promise<TItem[]>;
+    /**
+     * Create a new junction row linking `leftId` ↔ `rightId`.
+     *
+     * Goes through `SmrtCollection.create` which performs an upsert keyed on
+     * the model's `@smrt({ conflictColumns })`. Duplicates on the conflict key
+     * resolve to an UPDATE that rewrites every column — including the row's
+     * `id` and any timestamp columns — to the new instance's values. For most
+     * junctions that's fine: callers identify rows by (left, right, discriminator),
+     * not by junction-row-id, so id rewrites are invisible.
+     *
+     * If your junction table is externally addressable by id (e.g. its rows
+     * are exposed under `/api/v1/<table>/[id]`), override this method with a
+     * find-or-create check to preserve id stability across duplicate calls.
+     * See `ContentReferences.attach` for an example.
+     *
+     * @param opts - Extra fields to write into the row (e.g. `{ relationship, sortOrder, tenantId }`)
+     */
+    attach(leftId: string, rightId: string, opts?: JunctionAttachOptions): Promise<TItem>;
+    /**
+     * Delete all junction rows matching `leftId` + `rightId` (+ optional filter `opts`).
+     *
+     * @param opts - Additional WHERE filters (e.g. `{ relationship: 'thumbnail' }`)
+     */
+    detach(leftId: string, rightId: string, opts?: JunctionFilterOptions): Promise<void>;
+    /**
+     * Replace the full set of right-side rows for a `leftId`, scoped by `opts`.
+     *
+     * Behavior:
+     *  1. Snapshots and deletes existing rows matching `{ leftField: leftId, ...opts }`.
+     *  2. Creates a new row for each `rightId`, spreading `opts` into the row data.
+     *  3. If `positionField` is set and `opts` doesn't specify it, assigns the array index.
+     *
+     * Not transactional — partial failure leaves the table in a mixed state.
+     * For atomic replaces, wrap the call in your own DB transaction.
+     */
+    setLinks(leftId: string, rightIds: string[], opts?: JunctionAttachOptions): Promise<void>;
+}
+//# sourceMappingURL=junction.d.ts.map

package/dist/junction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"junction.d.ts","sourceRoot":"","sources":["../src/junction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAM5D,8BAAsB,YAAY,CAChC,KAAK,SAAS,UAAU,CACxB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAG,IAAI,CAAU;IAEhD,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAErC,gFAAgF;IAChF,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAEtC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAe;IAEjD;;;;;;;;;OASG;IACH,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAe;IAErD;;;OAGG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,KAAK,EAAE,CAAC;IAYnB;;;OAGG;IACG,OAAO,CACX,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,KAAK,EAAE,CAAC;IASnB;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,KAAK,CAAC;IAWjB;;;;OAIG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;;;OAUG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC;CAwBjB"}