@fjell/client-api 4.4.46 → 4.4.48

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/client-api",
   "description": "Client API for Fjell",
-  "version": "4.4.46",
+  "version": "4.4.48",
   "keywords": [
     "client",
     "api",
@@ -38,30 +38,31 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/core": "^4.4.50",
-    "@fjell/http-api": "^4.4.42",
-    "@fjell/logging": "^4.4.49",
-    "@fjell/registry": "^4.4.52",
+    "@fjell/core": "^4.4.53",
+    "@fjell/http-api": "^4.4.45",
+    "@fjell/logging": "^4.4.52",
+    "@fjell/registry": "^4.4.55",
     "deepmerge": "^4.3.1"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.33.0",
-    "@fjell/eslint-config": "^1.1.25",
+    "@eslint/js": "^9.38.0",
+    "@fjell/common-config": "^1.1.29",
     "@tsconfig/recommended": "^1.0.10",
-    "@types/node": "^24.2.1",
-    "@typescript-eslint/eslint-plugin": "^8.39.0",
-    "@typescript-eslint/parser": "^8.39.0",
-    "@vitest/coverage-istanbul": "^3.2.4",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/ui": "^3.2.4",
-    "concurrently": "^9.2.0",
-    "esbuild": "0.25.9",
-    "eslint": "^9.33.0",
-    "jsdom": "^26.1.0",
-    "typescript": "^5.9.2",
-    "undici": "^7.13.0",
-    "vitest": "^3.2.4",
+    "@types/node": "^24.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "@vitest/coverage-istanbul": "^4.0.1",
+    "@vitest/coverage-v8": "^4.0.1",
+    "@vitest/ui": "^4.0.1",
+    "concurrently": "^9.2.1",
+    "esbuild": "0.25.11",
+    "eslint": "^9.38.0",
+    "jsdom": "^27.0.1",
+    "prismjs": ">=1.30.0",
+    "typescript": "^5.9.3",
+    "undici": "^7.16.0",
+    "vitest": "^4.0.1",
     "vitest-fetch-mock": "^0.4.5"
   },
   "repository": {
@@ -69,6 +70,6 @@
     "url": "git+https://github.com/getfjell/client-api.git"
   },
   "overrides": {
-    "esbuild": "0.25.9"
+    "esbuild": "0.25.11"
   }
 }

package/LOCATION_KEY_ORDERING.md

@@ -1,153 +0,0 @@
-# Location Key Ordering in Client API
-
-## Overview
-
-When accessing nested/contained entities in Fjell, the **order of location keys matters**. The client API now includes **automatic validation** that will throw an error if location keys are passed in the wrong order, preventing malformed URL paths from being generated.
-
-## Automatic Validation (New Feature)
-
-As of this update, the client API automatically validates location key ordering and will throw a descriptive error if keys are out of order. This prevents silent failures where malformed paths would result in 404 errors.
-
-### What Gets Validated
-
-- Location keys must appear in ascending order according to the `pathNames` hierarchy
-- The validation compares each key's type (`kt`) against the `pathNames` array
-- If a key appears "earlier" in the hierarchy than the previous key, an error is thrown
-
-### Example Validation Error
-
-```typescript
-Error: Location keys must be ordered from parent to child according to the entity hierarchy.
-Expected order based on pathNames: [fjell/order, orderForm, orderNoseShape].
-Received key types in order: [orderForm, order].
-Key "order" is out of order - it should appear earlier in the hierarchy.
-```
-
-## How It Works
-
-The `getPath()` function in `Utilities.ts` processes keys in the order they are provided. The new `validateLocationKeyOrder()` function checks that location keys match the expected hierarchy before building the path.
-
-### Example: Three-Level Hierarchy
-
-Given this entity hierarchy:
-```
-order (primary)
-  └─ orderForm (contained in order)
-      └─ orderNoseShape (contained in orderForm)
-```
-
-With `pathNames: ["fjell/order", "orderForm", "orderNoseShape"]`
-
-### ✅ Correct Usage
-
-```typescript
-const orderKey: LocKey<"order"> = { kt: "order", lk: "26669" };
-const orderFormKey: LocKey<"orderForm"> = { kt: "orderForm", lk: "26693" };
-
-// Keys must be ordered from PARENT to CHILD
-const locations = [orderKey, orderFormKey];
-
-api.one({}, locations);
-// Result: /fjell/order/26669/orderForm/26693/orderNoseShape ✅
-```
-
-### ❌ Wrong Usage (Now Throws Error)
-
-```typescript
-// WRONG: orderForm before order
-const locations = [orderFormKey, orderKey];
-
-api.one({}, locations);
-// Throws Error: Location keys must be ordered from parent to child according to the entity hierarchy.
-// Expected order based on pathNames: [fjell/order, orderForm, orderNoseShape].
-// Received key types in order: [orderForm, order].
-// Key "order" is out of order - it should appear earlier in the hierarchy.
-```
-
-**Before this update:** This would have silently created a malformed path: `/orderForm/26693/fjell/order/26669/orderNoseShape`
-
-**Now:** An error is thrown immediately, making the issue obvious and preventing network requests with bad paths.
-
-## Rules for Location Key Ordering
-
-1. **Always order from outermost to innermost**: `[grandparent, parent, child]`
-2. **Match the hierarchy defined by your data model**: The order should reflect how entities are nested
-3. **For ComKeys**: The `loc` array should also follow this ordering
-
-### ComKey Example
-
-```typescript
-// For accessing a specific orderNoseShape item
-const comKey = {
-  kt: "orderNoseShape",
-  pk: "nose-123",
-  loc: [
-    { kt: "order", lk: "26669" },        // Parent first
-    { kt: "orderForm", lk: "26693" }     // Child second
-  ]
-};
-
-api.get(comKey);
-// Result: /fjell/order/26669/orderForm/26693/orderNoseShape/nose-123 ✅
-```
-
-## Debugging Tips
-
-1. **Enable logging**: The `Utilities.ts` logger logs the keys and pathNames being processed
-2. **Check the generated path**: Use browser DevTools Network tab to see the actual HTTP request
-3. **Verify key order**: Print/log your `locations` array before passing it to API methods
-4. **Use the type system**: TypeScript generics enforce the location types but not their order
-
-## Common Mistakes
-
-### Mistake 1: Building keys in reverse
-```typescript
-// Building keys as you traverse from child to parent
-const keys = [];
-keys.push(orderFormKey);  // ❌ Adding child first
-keys.push(orderKey);      // ❌ Adding parent second
-```
-
-**Fix**: Build keys from parent to child
-```typescript
-const keys = [];
-keys.push(orderKey);      // ✅ Parent first
-keys.push(orderFormKey);  // ✅ Child second
-```
-
-### Mistake 2: Not considering the full hierarchy
-```typescript
-// Only providing the immediate parent
-const locations = [orderFormKey];  // ❌ Missing orderKey
-```
-
-**Fix**: Include all ancestors
-```typescript
-const locations = [orderKey, orderFormKey];  // ✅ Complete hierarchy
-```
-
-## Test Coverage
-
-See `tests/Utilities.test.ts` for comprehensive examples:
-- ✅ Correct ordering: "should generate path for collection access with location keys only"
-- ✅ Error on wrong ordering: "should throw error when location keys are in wrong order"
-- ✅ ComKey usage: "should generate path for nested entities with correct order"
-- ✅ Error message validation: "should throw error with helpful message explaining the issue"
-
-## Benefits of Validation
-
-1. **Fail fast**: Errors are caught immediately at the API call site, not after a failed HTTP request
-2. **Clear error messages**: The error tells you exactly what went wrong and what the correct order should be
-3. **Prevents debugging confusion**: No more hunting through logs to figure out why you're getting 404 errors
-4. **Type-safe**: Works seamlessly with TypeScript's type system
-5. **Zero runtime cost for correct code**: Validation only runs when keys are actually used
-
-## Implementation Details
-
-The validation function (`validateLocationKeyOrder` in `Utilities.ts`):
-- Extracts location keys from the provided keys array
-- Builds a map of key types to their expected position in the hierarchy
-- Validates that location keys appear in strictly ascending order
-- Throws a detailed error if validation fails
-- Handles path segments with slashes (e.g., "fjell/order" matches key type "order")
-

package/LOCATION_KEY_VALIDATION_UPDATE.md

@@ -1,120 +0,0 @@
-# Location Key Validation Update
-
-## Summary
-
-Added automatic runtime validation to the `client-api` library that prevents location keys from being passed in the wrong order. This validation throws a clear, actionable error message instead of silently generating malformed URL paths.
-
-## Problem Being Solved
-
-Previously, if location keys were passed in the wrong order (e.g., `[orderFormKey, orderKey]` instead of `[orderKey, orderFormKey]`), the library would silently generate a malformed URL path like:
-```
-/orderForm/26693/fjell/order/26669/orderNoseShape
-```
-
-Instead of the correct:
-```
-/fjell/order/26669/orderForm/26693/orderNoseShape
-```
-
-This resulted in 404 errors that were difficult to debug.
-
-## Solution Implemented
-
-### 1. Runtime Validation Function
-
-Added `validateLocationKeyOrder()` in `src/Utilities.ts` that:
-- Extracts location keys from the provided keys array
-- Builds a map of key types to their expected hierarchy position
-- Validates that location keys appear in strictly ascending order
-- Handles path segments with slashes (e.g., "fjell/order" correctly matches key type "order")
-- Throws a descriptive error if validation fails
-
-### 2. Validation Error Message
-
-When keys are out of order, users get a clear error:
-```
-Error: Location keys must be ordered from parent to child according to the entity hierarchy.
-Expected order based on pathNames: [fjell/order, orderForm, orderNoseShape].
-Received key types in order: [orderForm, order].
-Key "order" is out of order - it should appear earlier in the hierarchy.
-```
-
-### 3. Test Coverage
-
-Added comprehensive tests in `tests/Utilities.test.ts`:
-- ✅ `should generate path for nested entities with correct order`
-- ✅ `should generate path for collection access with location keys only`
-- ✅ `should throw error when location keys are in wrong order`
-- ✅ `should throw error with helpful message explaining the issue`
-
-### 4. Documentation
-
-Created/updated documentation:
-- `LOCATION_KEY_ORDERING.md` - Complete guide on location key ordering with examples
-- Explains the validation, shows correct vs incorrect usage
-- Documents benefits and implementation details
-
-## Benefits
-
-1. **Fail Fast**: Errors caught at API call site, not after HTTP request
-2. **Clear Error Messages**: Tells exactly what's wrong and the correct order
-3. **Prevents Debugging Confusion**: No more hunting through logs for 404 causes
-4. **Type-Safe + Runtime Safe**: TypeScript types prevent wrong order at compile time, runtime validation catches dynamic cases
-5. **Zero Performance Cost for Correct Code**: Validation only runs when building paths
-
-## Backwards Compatibility
-
-✅ **Fully backwards compatible** - only throws errors for code that was already broken (passing keys in wrong order, which would have resulted in 404s)
-
-## Files Changed
-
-1. `src/Utilities.ts` - Added `validateLocationKeyOrder()` function and integrated it into `getPath()`
-2. `tests/Utilities.test.ts` - Added 4 new tests for validation behavior
-3. `LOCATION_KEY_ORDERING.md` - New comprehensive documentation
-4. `LOCATION_KEY_VALIDATION_UPDATE.md` - This summary document
-
-## Test Results
-
-All 302 tests pass across the entire test suite:
-```
-Test Files  22 passed (22)
-Tests  302 passed (302)
-```
-
-Coverage for `Utilities.ts`: **94.97%**
-
-## Example Usage
-
-### Before (Silent Failure)
-```typescript
-const locations = [orderFormKey, orderKey]; // Wrong order!
-const items = await api.one({}, locations);
-// Result: 404 error with confusing path
-```
-
-### After (Clear Error)
-```typescript
-const locations = [orderFormKey, orderKey]; // Wrong order!
-const items = await api.one({}, locations);
-// Throws immediately:
-// Error: Location keys must be ordered from parent to child...
-```
-
-### Correct Usage
-```typescript
-const locations = [orderKey, orderFormKey]; // Correct order!
-const items = await api.one({}, locations);
-// Result: Success! ✅
-```
-
-## Recommendation for Your Project
-
-In your other project where you're experiencing the path ordering issue:
-
-1. **Update the `@fjell/client-api` dependency** to get this validation
-2. **Run your code** - the validation will immediately show you where keys are in wrong order
-3. **Fix the order** based on the error messages
-4. **Verify** the fix by checking that API calls succeed
-
-The validation will pinpoint exactly which API calls have keys in the wrong order and what the correct order should be.
-

package/MIGRATION_v3.md

@@ -1,231 +0,0 @@
-# Migration Guide: v4.4.x to v4.5.0
-
-## Overview
-
-Version 4.5.0 adopts the Operations interface from `@fjell/core`, providing a consistent API across all Fjell packages.
-
-## Breaking Changes Summary
-
-1. **Core Operations Interface**: `ClientApi` now extends `Operations` from `@fjell/core`
-2. **Create Method**: Changed signature to use `CreateOptions`
-3. **Action Methods**: Parameter name changed from `body` to `params`
-4. **Upsert Operation**: Added missing `upsert` method
-
-## Dependency Updates
-
-Update your `package.json`:
-
-```bash
-npm install @fjell/core@latest @fjell/client-api@latest
-```
-
-## Code Migration
-
-### 1. Create Method
-
-The `create` method now uses `CreateOptions` instead of a simple `locations` parameter.
-
-#### Before (v4.4.x)
-
-```typescript
-// With locations
-const item = await api.create(
-  { name: 'Alice' },
-  [{ kt: 'org', lk: 'org-123' }]
-);
-
-// Without locations
-const item = await api.create({ name: 'Alice' });
-```
-
-#### After (v4.5.0)
-
-```typescript
-// With locations - wrap in options object
-const item = await api.create(
-  { name: 'Alice' },
-  { locations: [{ kt: 'org', lk: 'org-123' }] }
-);
-
-// Without locations - omit options or pass undefined
-const item = await api.create({ name: 'Alice' });
-
-// NEW: With specific key
-const item = await api.create(
-  { name: 'Alice' },
-  { key: { kt: 'user', pk: 'custom-id' } }
-);
-```
-
-### 2. Action Methods
-
-The parameter name changed from `body` to `params` to match the core Operations interface. **Functionally, it's the same** - just a naming change.
-
-#### Before (v4.4.x)
-
-```typescript
-const [item, affectedKeys] = await api.action(
-  key,
-  'promote',
-  { role: 'admin' } // called "body"
-);
-
-const [items, affectedKeys] = await api.allAction(
-  'archive',
-  { reason: 'expired' }, // called "body"
-  locations
-);
-```
-
-#### After (v4.5.0)
-
-```typescript
-// Same code - just know it's now called "params" internally
-const [item, affectedKeys] = await api.action(
-  key,
-  'promote',
-  { role: 'admin' } // now called "params"
-);
-
-const [items, affectedKeys] = await api.allAction(
-  'archive',
-  { reason: 'expired' }, // now called "params"
-  locations
-);
-```
-
-### 3. Upsert Operation (New)
-
-A new `upsert` operation is now available:
-
-```typescript
-// Creates if doesn't exist, updates if it does
-const user = await api.upsert(
-  { kt: 'user', pk: 'user-123' },
-  { name: 'Alice', email: 'alice@example.com' }
-);
-
-// With locations (for contained items)
-const comment = await api.upsert(
-  { kt: 'comment', pk: 'comment-456', loc: [{ kt: 'post', lk: 'post-123' }] },
-  { text: 'Updated comment' },
-  [{ kt: 'post', lk: 'post-123' }]
-);
-```
-
-### 4. Type Imports
-
-Import types from the appropriate package:
-
-#### Before (v4.4.x)
-
-```typescript
-import { ClientApi } from '@fjell/client-api';
-// No OperationParams or AffectedKeys available
-```
-
-#### After (v4.5.0)
-
-```typescript
-import { ClientApi, OperationParams, AffectedKeys, CreateOptions } from '@fjell/client-api';
-// Or import directly from core
-import { Operations, OperationParams, AffectedKeys } from '@fjell/core';
-```
-
-## Type Compatibility
-
-The `ClientApi` interface is now fully compatible with the core `Operations` interface:
-
-```typescript
-import type { Operations } from '@fjell/core';
-import type { ClientApi } from '@fjell/client-api';
-
-// These are now compatible
-function processItems(ops: Operations<User, 'user'>) {
-  // Can pass either ClientApi or any other Operations implementation
-}
-
-const clientApi: ClientApi<User, 'user'> = ...;
-processItems(clientApi); // ✅ Works!
-```
-
-## Benefits of Migration
-
-### 1. Consistent Interface
-
-All Fjell packages now share the same Operations interface:
-
-```typescript
-// All implement the same Operations interface
-import { Operations } from '@fjell/lib';
-import { ClientApi } from '@fjell/client-api';
-import { Operations as FirestoreOps } from '@fjell/lib-firestore';
-
-// Can be used interchangeably
-function workWithOperations(ops: Operations<Item, string>) {
-  // Works with any implementation
-}
-```
-
-### 2. Better Type Safety
-
-```typescript
-import { OperationParams, AffectedKeys, CreateOptions } from '@fjell/core';
-
-// Strongly typed parameters
-const params: OperationParams = {
-  status: 'active',
-  limit: 10
-};
-
-// Type-safe create options
-const options: CreateOptions<'user'> = {
-  key: { kt: 'user', pk: 'user-123' }
-};
-```
-
-### 3. Future Compatibility
-
-By adopting the core interface, your code will be compatible with future Fjell enhancements and new operation implementations.
-
-## Troubleshooting
-
-### TypeScript Errors
-
-If you see TypeScript errors after upgrading:
-
-1. **Clear your TypeScript cache**: Delete `node_modules/.cache` and `dist/` directories
-2. **Rebuild**: Run `npm run build`
-3. **Update imports**: Ensure you're importing types from the correct packages
-
-### Runtime Errors
-
-If you encounter runtime errors:
-
-1. **Check create calls**: Wrap `locations` in options object: `{ locations: [...] }`
-2. **Verify dependencies**: Ensure `@fjell/core` is at the latest version
-3. **Clear node_modules**: Delete and reinstall if necessary
-
-## Migration Checklist
-
-- [ ] Update package.json dependencies
-- [ ] Run `npm install`
-- [ ] Update `create` calls to use options object
-- [ ] Update any type imports
-- [ ] Test upsert operations if needed
-- [ ] Run tests: `npm test`
-- [ ] Build: `npm run build`
-- [ ] Check for TypeScript errors: `npm run lint`
-
-## Questions or Issues?
-
-If you encounter any problems during migration:
-
-1. Check the [API Reference](./docs/public/api-reference.md)
-2. Review the [examples](./examples/)
-3. File an issue on GitHub
-
-## Previous Migrations
-
-- For migrations from older versions, see previous migration guides
-

package/vitest.config.ts

@@ -1,22 +0,0 @@
-/// <reference types="vitest" />
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    environment: 'jsdom',
-    setupFiles: ['./tests/setup.ts'],
-    globals: true,
-    testTimeout: 30000,
-    coverage: {
-      exclude: [
-        'build.js',
-        'docs/**',
-        'coverage/**',
-        'output/**',
-        '**/*.config.*',
-        '**/*.d.ts',
-        'dist/**',
-      ]
-    }
-  },
-})