@fjell/core 4.4.77 → 4.4.79

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Fjell Project
+   Copyright 2026 Tim O'Brien
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/dist/index.js

@@ -6,10 +6,10 @@ var logger_default = LibLogger;
 // src/key/KUtils.ts
 var logger = logger_default.get("KUtils");
 var isComKey = (key) => {
-  return key !== null && typeof key === "object" && "kt" in key && "pk" in key && "loc" in key && Array.isArray(key.loc) && key.loc.length > 0;
+  return key !== null && typeof key === "object" && "kt" in key && "pk" in key && "loc" in key && Array.isArray(key.loc);
 };
 var isPriKey = (key) => {
-  return key !== null && typeof key === "object" && "kt" in key && "pk" in key && (!("loc" in key) || !key.loc || Array.isArray(key.loc) && key.loc.length === 0);
+  return key !== null && typeof key === "object" && "kt" in key && "pk" in key && (!("loc" in key) || key.loc === void 0 || key.loc === null);
 };
 var normalizeKeyValue = (value) => {
   return String(value);
@@ -264,9 +264,9 @@ var isValidItemKey = (key) => {
 };
 var lkaToIK = locKeyArrayToItemKey;
 
-// node_modules/@fjell/types/dist/chunk-5M6KJZFD.js
+// node_modules/@fjell/types/dist/chunk-C37JAZMK.js
 var isCondition = (condition) => {
-  return (typeof condition.column === "string" && (Array.isArray(condition.value) && condition.value.every((item) => typeof item === "string")) || Array.isArray(condition.value) && condition.value.every((item) => typeof item === "number") || typeof condition.value === "string" || typeof condition.value === "number" || typeof condition.value === "boolean" || condition.value instanceof Date || condition.value === null) && (condition.operator ? typeof condition.operator === "string" : true);
+  return typeof condition.column === "string" && (Array.isArray(condition.value) && condition.value.every((item) => typeof item === "string") || Array.isArray(condition.value) && condition.value.every((item) => typeof item === "number") || typeof condition.value === "string" || typeof condition.value === "number" || typeof condition.value === "boolean" || condition.value instanceof Date || condition.value === null) && (condition.operator ? typeof condition.operator === "string" : true);
 };
 
 // src/item/IQFactory.ts

package/guide/index.md

@@ -0,0 +1,30 @@
+# @fjell/core - Agentic Guide
+
+## Purpose
+
+Core Item/Key framework and base abstractions used by higher-level Fjell libraries.
+
+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
+
+- Provides item factories and coordinate creation helpers
+- Defines shared dictionaries, operation contracts, and event abstractions
+- Supplies reusable primitives consumed by @fjell/lib and providers
+
+## Installation
+
+```bash
+npm install @fjell/core
+```
+
+## Public API Highlights
+
+- `IQFactory`, `IFactory`, and `AItemService`
+- `createCoordinate` and dictionary exports
+- Shared errors, operations, and event exports

package/guide/integration.md

@@ -0,0 +1,32 @@
+# Integration Guide
+
+Guide for integrating `@fjell/core` into larger Fjell-based systems.
+
+## Where It Fits
+
+Core Item/Key framework and base abstractions used by higher-level Fjell libraries.
+
+## Recommended Integration Pattern
+
+- Use @fjell/core when building new storage adapters or framework extensions
+- Keep coordinate conventions consistent with backend libraries to avoid key mismatches
+- Use shared errors/events to keep telemetry and retry behavior uniform
+
+## 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/core`.
+
+## Installation
+
+```bash
+npm install @fjell/core
+```
+
+## API Highlights
+
+- `IQFactory`, `IFactory`, and `AItemService`
+- `createCoordinate` and dictionary exports
+- Shared errors, operations, and event exports
+
+## Quick Example
+
+```ts
+import { createCoordinate, IFactory } from "@fjell/core";
+
+const coordinate = createCoordinate({
+  scope: "widget",
+  itemType: ["tenant", "widget"],
+});
+
+const factory = new IFactory();
+const key = factory.key({ tenantId: "t1", widgetId: "w1" }, coordinate);
+```
+
+## Model Consumption Rules
+
+1. Import from the package root (`@fjell/core`) 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,7 +1,7 @@
 {
   "name": "@fjell/core",
   "description": "Core Item and Key Framework for Fjell",
-  "version": "4.4.77",
+  "version": "4.4.79",
   "keywords": [
     "core",
     "fjell"
@@ -36,16 +36,16 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/logging": "^4.4.67",
-    "@fjell/types": "4.4.7",
-    "@fjell/validation": "4.4.4",
+    "@fjell/logging": "^4.4.72",
+    "@fjell/types": "^4.4.9",
+    "@fjell/validation": "^4.4.6",
     "deepmerge": "^4.3.1",
     "luxon": "^3.7.2"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.39.1",
-    "@fjell/common-config": "^1.1.37",
+    "@fjell/common-config": "^1.1.38",
     "@swc/core": "^1.15.2",
     "@tsconfig/recommended": "^1.0.13",
     "@types/luxon": "^3.7.1",