@fjell/lib-sequelize 4.4.83 → 4.4.85

package/dist/primary/SequelizeLibrary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SequelizeLibrary.d.ts","sourceRoot":"","sources":["../../src/primary/SequelizeLibrary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,OAAO,KAAK,OAAO,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAiB,OAAO,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAoB,MAAM,eAAe,CAAC;AAM7D,MAAM,WAAW,gBAAgB,CAC/B,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EACjB,CAAC,SAAS,MAAM;IAEhB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CACpC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EACjB,CAAC,SAAS,MAAM,EAEhB,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAC1B,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAK,EACvC,MAAM,EAAE,MAAM,EAAE,YAAK,EACrB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAoBxB"}
+{"version":3,"file":"SequelizeLibrary.d.ts","sourceRoot":"","sources":["../../src/primary/SequelizeLibrary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,OAAO,KAAK,OAAO,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAiB,OAAO,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAoB,MAAM,eAAe,CAAC;AAW7D,MAAM,WAAW,gBAAgB,CAC/B,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EACjB,CAAC,SAAS,MAAM;IAEhB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CACpC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,EACjB,CAAC,SAAS,MAAM,EAEhB,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAC1B,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAK,EACvC,MAAM,EAAE,MAAM,EAAE,YAAK,EACrB,QAAQ,EAAE,QAAQ,GACjB,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAwCxB"}

package/dist/util/SequelizeInstanceWrapper.d.ts

@@ -0,0 +1,52 @@
+import { Model, ModelStatic } from 'sequelize';
+export type DirectSaveBehavior = 'warn-and-throw' | 'warn-only';
+/**
+ * Configuration for Sequelize instance wrapping behavior
+ */
+export interface SequelizeWrapperConfig {
+    /**
+     * Behavior when save() or update() is called directly on a Sequelize instance
+     * - 'warn-and-throw': Log a warning and throw an error (default)
+     * - 'warn-only': Log a warning but allow the operation to proceed
+     */
+    directSaveBehavior?: DirectSaveBehavior;
+    /**
+     * The item type (kt) for better error messages
+     */
+    itemType?: string;
+    /**
+     * Whether hooks are defined for this library
+     */
+    hasHooks?: boolean;
+}
+/**
+ * Wraps a Sequelize Model instance to intercept direct save() and update() calls
+ * that would bypass Fjell hooks.
+ *
+ * @param instance - The Sequelize Model instance to wrap
+ * @param config - Configuration for wrapper behavior
+ * @returns A wrapped instance that intercepts save() and update() calls
+ */
+export declare function wrapSequelizeInstance<T extends Model>(instance: T, config?: SequelizeWrapperConfig): T;
+/**
+ * Checks if a Sequelize library has hooks defined
+ */
+export declare function hasHooksDefined(options: {
+    hooks?: any;
+    validators?: any;
+}): boolean;
+/**
+ * Wraps a Sequelize ModelStatic class so that queries return wrapped instances.
+ * This ensures that when actions/facets query models directly via library.models,
+ * they receive wrapped instances that intercept direct save()/update() calls.
+ *
+ * @param modelClass - The Sequelize ModelStatic class to wrap
+ * @param config - Configuration for wrapper behavior
+ * @returns A wrapped ModelStatic that returns wrapped instances from queries
+ */
+export declare function wrapSequelizeModel<T extends ModelStatic<Model>>(modelClass: T, config?: SequelizeWrapperConfig): T;
+/**
+ * Wraps an array of Sequelize ModelStatic classes
+ */
+export declare function wrapSequelizeModels(models: ModelStatic<any>[], config?: SequelizeWrapperConfig): ModelStatic<any>[];
+//# sourceMappingURL=SequelizeInstanceWrapper.d.ts.map

package/dist/util/SequelizeInstanceWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SequelizeInstanceWrapper.d.ts","sourceRoot":"","sources":["../../src/util/SequelizeInstanceWrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAK/C,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAcD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,KAAK,EACnD,QAAQ,EAAE,CAAC,EACX,MAAM,GAAE,sBAA2B,GAClC,CAAC,CAoHH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,GAAG,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAA;CAAE,GAAG,OAAO,CAYnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,WAAW,CAAC,KAAK,CAAC,EAC7D,UAAU,EAAE,CAAC,EACb,MAAM,GAAE,sBAA2B,GAClC,CAAC,CAgFH;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAC1B,MAAM,GAAE,sBAA2B,GAClC,WAAW,CAAC,GAAG,CAAC,EAAE,CAEpB"}

package/guide/index.md

@@ -0,0 +1,30 @@
+# @fjell/lib-sequelize - Agentic Guide
+
+## Purpose
+
+Sequelize-backed Fjell library implementation for relational database persistence.
+
+This guide is optimized for AI-assisted code generation and integration workflows.
+
+## Documentation
+
+- **[Usage Guide](./usage.md)** - API-oriented usage patterns and model-safe examples
+- **[Integration Guide](./integration.md)** - Architecture placement, composition rules, and implementation guidance
+
+## Key Capabilities
+
+- Implements primary and contained operations on Sequelize models
+- Provides definition and coordinate helpers for relational mappings
+- Includes reference builder and Sequelize instance wrapper utilities
+
+## Installation
+
+```bash
+npm install @fjell/lib-sequelize
+```
+
+## Public API Highlights
+
+- `SequelizeLibrary` and `SequelizeLibraryFactory`
+- `createCoordinate`, `SCOPE_SEQUELIZE`, and definition/options exports
+- `ReferenceBuilder` and `SequelizeInstanceWrapper` utilities

package/guide/integration.md

@@ -0,0 +1,32 @@
+# Integration Guide
+
+Guide for integrating `@fjell/lib-sequelize` into larger Fjell-based systems.
+
+## Where It Fits
+
+Sequelize-backed Fjell library implementation for relational database persistence.
+
+## Recommended Integration Pattern
+
+- Coordinate Sequelize model definitions with Fjell key conventions before first deployment
+- Use transaction boundaries around multi-step provider operations
+- Tune eager/lazy loading and indexing for predictable query performance
+
+## System Composition Checklist
+
+- Define package boundaries: schema/types, transport, operations, adapters, and UI.
+- Keep contracts stable by sharing @fjell/types interfaces where applicable.
+- Centralize retries/timeouts/logging around infrastructure-facing operations.
+- Validate inputs at API boundaries before invoking persistence or provider layers.
+- Add contract and integration tests for every generated workflow.
+
+## Cross-Library Pairings
+
+- Pair with @fjell/types for shared contracts.
+- Pair with @fjell/validation for input and schema checks.
+- Pair with @fjell/logging for observability in integration flows.
+- Pair with storage/router/provider packages based on your runtime architecture.
+
+## Integration Example Shape
+
+Use this package behind an application service layer that exposes stable domain methods. Generated code should call those service methods, not raw infrastructure primitives, unless your architecture intentionally keeps infrastructure at the edge.

package/guide/usage.md

@@ -0,0 +1,43 @@
+# Usage Guide
+
+Comprehensive usage guidance for `@fjell/lib-sequelize`.
+
+## Installation
+
+```bash
+npm install @fjell/lib-sequelize
+```
+
+## API Highlights
+
+- `SequelizeLibrary` and `SequelizeLibraryFactory`
+- `createCoordinate`, `SCOPE_SEQUELIZE`, and definition/options exports
+- `ReferenceBuilder` and `SequelizeInstanceWrapper` utilities
+
+## Quick Example
+
+```ts
+import { SequelizeLibraryFactory } from "@fjell/lib-sequelize";
+
+const factory = new SequelizeLibraryFactory({
+  sequelize,
+  tablePrefix: "fjell",
+});
+
+const library = factory.createPrimaryLibrary();
+await library.save({ pri: { pk: "widget#1", sk: "meta" }, name: "Widget One" });
+```
+
+## Model Consumption Rules
+
+1. Import from the package root (`@fjell/lib-sequelize`) instead of deep-internal paths unless explicitly documented.
+2. Keep usage aligned with exported public symbols listed in this guide.
+3. Prefer explicit typing at package boundaries so generated code remains robust during upgrades.
+4. Keep error handling deterministic and map infrastructure failures into domain-level errors.
+5. Co-locate integration wrappers in your app so model-generated code has one canonical entry point.
+
+## Best Practices
+
+- Keep examples and abstractions consistent with existing Fjell package conventions.
+- Favor composable wrappers over one-off inline integration logic.
+- Add targeted tests around generated integration code paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjell/lib-sequelize",
-  "version": "4.4.83",
+  "version": "4.4.85",
   "license": "Apache-2.0",
   "keywords": [
     "library",
@@ -25,7 +25,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "guide"
   ],
   "scripts": {
     "build": "npm run lint && node build.js",
@@ -41,12 +42,12 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/core": "^4.4.76",
-    "@fjell/lib": "^4.4.86",
-    "@fjell/logging": "^4.4.66",
-    "@fjell/registry": "^4.4.83",
-    "@fjell/types": "^4.4.6",
-    "@fjell/validation": "^4.4.3",
+    "@fjell/core": "^4.4.79",
+    "@fjell/lib": "^4.4.89",
+    "@fjell/logging": "^4.4.72",
+    "@fjell/registry": "^4.4.86",
+    "@fjell/types": "^4.4.9",
+    "@fjell/validation": "^4.4.6",
     "dayjs": "^1.11.13",
     "deepmerge": "^4.3.1",
     "sequelize": "^6.37.7",
@@ -55,7 +56,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.32.0",
-    "@fjell/common-config": "^1.1.36",
+    "@fjell/common-config": "^1.1.38",
     "@swc/core": "^1.13.2",
     "@tsconfig/recommended": "^1.0.10",
     "@types/node": "^24.1.0",
@@ -72,6 +73,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/getfjell/lib-sequelize.git"
+    "url": "git+https://github.com/fjellgrunn/lib-sequelize.git"
   }
 }