@fjell/registry 4.4.22 → 4.4.24

package/docs/public/operations/get.md

@@ -0,0 +1,389 @@
+# `get` Operation
+
+Retrieve a single item by its key with automatic error handling and retry logic.
+
+## Syntax
+
+### Primary Items (PItemApi)
+```typescript
+async get(key: PriKey<S>): Promise<V | null>
+```
+
+### Contained Items (CItemApi)
+```typescript
+async get(key: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>): Promise<V | null>
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `key` | `PriKey<S>` or `ComKey<S, ...>` | Yes | Key identifying the item to retrieve |
+
+### Key Types
+
+```typescript
+// Primary Key (for PItemApi)
+interface PriKey<S> {
+  keyType: S;
+  pk: string;
+}
+
+// Composite Key (for CItemApi)
+interface ComKey<S, L1, L2, L3, L4, L5> {
+  keyType: S;
+  pk: string;
+  l1?: LocKey<L1>;
+  l2?: LocKey<L2>;
+  // ... up to l5
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Get a user by ID
+const userKey = { keyType: 'user', pk: 'user-123' };
+const user = await userApi.get(userKey);
+
+if (user) {
+  console.log('Found user:', user.name);
+} else {
+  console.log('User not found');
+}
+```
+
+### Contained Items
+
+```typescript
+// Get a task with composite key
+const taskKey = {
+  keyType: 'task',
+  pk: 'task-456',
+  l1: { lkType: 'user', lk: 'user-123' }
+};
+
+const task = await taskApi.get(taskKey);
+```
+
+### Error Handling
+
+```typescript
+try {
+  const user = await userApi.get(userKey);
+
+  if (!user) {
+    console.log('User not found - this is normal');
+    return;
+  }
+
+  console.log('User found:', user.name);
+
+} catch (error) {
+  if (error.code === 'NETWORK_ERROR') {
+    console.error('Network issue - operation was automatically retried');
+  } else if (error.code === 'AUTHENTICATION_ERROR') {
+    console.error('Authentication failed - check credentials');
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
+}
+```
+
+### Null Handling Patterns
+
+```typescript
+// Pattern 1: Explicit null check
+const user = await userApi.get(userKey);
+if (user === null) {
+  throw new Error('User not found');
+}
+// user is now typed as V (not null)
+
+// Pattern 2: Default fallback
+const user = await userApi.get(userKey) ?? createDefaultUser();
+
+// Pattern 3: Optional chaining
+const userName = (await userApi.get(userKey))?.name ?? 'Unknown';
+```
+
+## Return Value
+
+Returns `Promise<V | null>`:
+- **V**: The found item with all its properties
+- **null**: When item is not found (404 response)
+
+```typescript
+// Found item structure
+const user = await userApi.get(userKey);
+// {
+//   id: 'user-123',
+//   name: 'John Doe',
+//   email: 'john@example.com',
+//   active: true,
+//   createdAt: '2024-01-15T10:30:00Z',
+//   updatedAt: '2024-01-20T14:22:00Z',
+//   keyType: 'user'
+// }
+
+// Not found
+const missingUser = await userApi.get({ keyType: 'user', pk: 'nonexistent' });
+// null
+```
+
+## Performance Optimization
+
+### Caching Strategies
+
+```typescript
+// Simple memory cache
+const userCache = new Map<string, User>();
+
+async function getCachedUser(userKey: PriKey<'user'>): Promise<User | null> {
+  const cacheKey = `user:${userKey.pk}`;
+
+  // Check cache first
+  if (userCache.has(cacheKey)) {
+    return userCache.get(cacheKey)!;
+  }
+
+  // Fetch from API
+  const user = await userApi.get(userKey);
+
+  // Cache the result (including null)
+  if (user) {
+    userCache.set(cacheKey, user);
+  }
+
+  return user;
+}
+```
+
+### Batch Loading
+
+```typescript
+// Load multiple items efficiently
+async function getUsersBatch(userKeys: PriKey<'user'>[]): Promise<(User | null)[]> {
+  // Use Promise.all for parallel requests
+  const promises = userKeys.map(key =>
+    userApi.get(key).catch(error => {
+      console.error(`Failed to load user ${key.pk}:`, error.message);
+      return null;
+    })
+  );
+
+  return Promise.all(promises);
+}
+```
+
+## Advanced Patterns
+
+### Safe Get with Type Guards
+
+```typescript
+// Type-safe retrieval with validation
+async function getValidUser(userKey: PriKey<'user'>): Promise<User> {
+  const user = await userApi.get(userKey);
+
+  if (!user) {
+    throw new Error(`User ${userKey.pk} not found`);
+  }
+
+  if (!user.active) {
+    throw new Error(`User ${userKey.pk} is inactive`);
+  }
+
+  return user;
+}
+```
+
+### Retry with Custom Logic
+
+```typescript
+// Get with custom retry behavior
+async function getWithRetry<T>(
+  apiCall: () => Promise<T | null>,
+  maxAttempts: number = 3,
+  delay: number = 1000
+): Promise<T | null> {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await apiCall();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+
+      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+      delay *= 2; // Exponential backoff
+    }
+  }
+  return null;
+}
+
+// Usage
+const user = await getWithRetry(() => userApi.get(userKey));
+```
+
+### Get with Fallback Chain
+
+```typescript
+// Try multiple sources for data
+async function getUserWithFallbacks(userId: string): Promise<User | null> {
+  const userKey = { keyType: 'user' as const, pk: userId };
+
+  // Try primary API
+  try {
+    const user = await userApi.get(userKey);
+    if (user) return user;
+  } catch (error) {
+    console.warn('Primary API failed:', error.message);
+  }
+
+  // Try backup API
+  try {
+    const user = await backupUserApi.get(userKey);
+    if (user) return user;
+  } catch (error) {
+    console.warn('Backup API failed:', error.message);
+  }
+
+  // Try cache
+  try {
+    const cachedUser = await getUserFromCache(userId);
+    if (cachedUser) return cachedUser;
+  } catch (error) {
+    console.warn('Cache failed:', error.message);
+  }
+
+  return null;
+}
+```
+
+## Common Use Cases
+
+### User Profile Loading
+
+```typescript
+// Load user with profile data
+async function loadUserProfile(userId: string) {
+  const userKey = { keyType: 'user' as const, pk: userId };
+  const user = await userApi.get(userKey);
+
+  if (!user) {
+    throw new Error('User not found');
+  }
+
+  // Load related data
+  const [profile, preferences, activity] = await Promise.all([
+    profileApi.get({ keyType: 'profile', pk: userId }),
+    preferencesApi.get({ keyType: 'preferences', pk: userId }),
+    activityApi.allFacet('recent-activity', { limit: 10 }, [userId])
+  ]);
+
+  return {
+    user,
+    profile,
+    preferences,
+    activity
+  };
+}
+```
+
+### Resource Validation
+
+```typescript
+// Validate resource exists before operation
+async function updateUserIfExists(
+  userKey: PriKey<'user'>,
+  updates: Partial<User>
+): Promise<User | null> {
+  const user = await userApi.get(userKey);
+
+  if (!user) {
+    console.log('User not found, skipping update');
+    return null;
+  }
+
+  // User exists, proceed with update
+  return await userApi.update(userKey, updates);
+}
+```
+
+### Conditional Operations
+
+```typescript
+// Perform operation based on item state
+async function processUserBasedOnState(userKey: PriKey<'user'>) {
+  const user = await userApi.get(userKey);
+
+  if (!user) {
+    console.log('User not found');
+    return;
+  }
+
+  switch (user.status) {
+    case 'pending':
+      await userApi.action(userKey, 'send-welcome-email');
+      break;
+
+    case 'active':
+      await userApi.action(userKey, 'update-last-seen');
+      break;
+
+    case 'suspended':
+      console.log('User is suspended, no action taken');
+      break;
+
+    default:
+      console.log('Unknown user status:', user.status);
+  }
+}
+```
+
+## Error Scenarios
+
+### Network Issues
+
+```typescript
+// Automatic retry handles network issues
+try {
+  const user = await userApi.get(userKey);
+  // Network errors are automatically retried
+} catch (error) {
+  // Only non-retryable errors reach here
+  if (error.code === 'NETWORK_ERROR') {
+    // All retries exhausted
+    console.error('Network completely unavailable');
+  }
+}
+```
+
+### Authorization
+
+```typescript
+// Handle permission issues
+try {
+  const user = await userApi.get(userKey);
+} catch (error) {
+  if (error.code === 'AUTHORIZATION_ERROR') {
+    console.error('Insufficient permissions to access user');
+    // Redirect to login or show error message
+  }
+}
+```
+
+## Related Operations
+
+- [`all`](./all.md) - Get multiple items
+- [`one`](./one.md) - Get single item with query
+- [`find`](./find.md) - Find items with custom finders
+- [`create`](./create.md) - Create new items
+- [`update`](./update.md) - Update existing items
+
+## Next Steps
+
+- Explore [Caching Strategies](../guides/caching.md)
+- Learn about [Error Handling](../error-handling/README.md)
+- Review [Performance Optimization](../guides/performance.md)

package/docs/public/package.json

@@ -24,7 +24,7 @@
     "build": "tsc --noEmit && vite build",
     "dev": "concurrently \"tsc --watch --noEmit\" \"vite build --watch\"",
     "lint": "eslint . --ext .ts --fix",
-    "clean": "rimraf dist",
+    "clean": "rm -rf dist",
     "test": "npm run lint && vitest run --coverage",
     "test:memory:optimized": "npm run lint && NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/memory.test.ts",
     "test:timing:optimized": "npm run lint && NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/timing.test.ts",
@@ -48,7 +48,6 @@
     "concurrently": "^9.2.0",
     "eslint": "^9.31.0",
     "nodemon": "^3.1.10",
-    "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.8.3",

package/docs/timing-range.svg

@@ -31,16 +31,18 @@
   <g transform="translate(110,60)">
 
     <!-- Grid lines (logarithmic scale) -->
-    <line x1="0" y1="409.4248343333136" x2="1015" y2="409.4248343333136" class="grid"/>
-    <text x="-10" y="413.4248343333136" text-anchor="end" class="label">0.20µs</text>
-    <line x1="0" y1="315.6500962348101" x2="1015" y2="315.6500962348101" class="grid"/>
-    <text x="-10" y="319.6500962348101" text-anchor="end" class="label">0.50µs</text>
-    <line x1="0" y1="244.7122453326445" x2="1015" y2="244.7122453326445" class="grid"/>
-    <text x="-10" y="248.7122453326445" text-anchor="end" class="label">1.0µs</text>
-    <line x1="0" y1="173.77439443047894" x2="1015" y2="173.77439443047894" class="grid"/>
-    <text x="-10" y="177.77439443047894" text-anchor="end" class="label">2.0µs</text>
-    <line x1="0" y1="79.99965633197542" x2="1015" y2="79.99965633197542" class="grid"/>
-    <text x="-10" y="83.99965633197542" text-anchor="end" class="label">5.0µs</text>
+    <line x1="0" y1="457.6666713805134" x2="1015" y2="457.6666713805134" class="grid"/>
+    <text x="-10" y="461.6666713805134" text-anchor="end" class="label">0.10µs</text>
+    <line x1="0" y1="387.70544969582414" x2="1015" y2="387.70544969582414" class="grid"/>
+    <text x="-10" y="391.70544969582414" text-anchor="end" class="label">0.20µs</text>
+    <line x1="0" y1="295.22174519819055" x2="1015" y2="295.22174519819055" class="grid"/>
+    <text x="-10" y="299.22174519819055" text-anchor="end" class="label">0.50µs</text>
+    <line x1="0" y1="225.26052351350134" x2="1015" y2="225.26052351350134" class="grid"/>
+    <text x="-10" y="229.26052351350134" text-anchor="end" class="label">1.0µs</text>
+    <line x1="0" y1="155.29930182881213" x2="1015" y2="155.29930182881213" class="grid"/>
+    <text x="-10" y="159.29930182881213" text-anchor="end" class="label">2.0µs</text>
+    <line x1="0" y1="62.815597331178594" x2="1015" y2="62.815597331178594" class="grid"/>
+    <text x="-10" y="66.8155973311786" text-anchor="end" class="label">5.0µs</text>
     <line x1="0" y1="0" x2="0" y2="460" class="grid"/>
     <text x="0" y="480" text-anchor="middle" class="label">10</text>
     <line x1="76.38636139973525" y1="0" x2="76.38636139973525" y2="460" class="grid"/>
@@ -76,34 +78,34 @@
     <!-- Axis labels -->
     <text x="507.5" y="510" text-anchor="middle" class="axis-title">Tree Size (items) - Log Scale</text>
     <text transform="rotate(-90,-70,230)" x="-70" y="230" text-anchor="middle" class="axis-title">Execution Time (µs)</text>
-    <path d="M 0 135.24798501632807 L 76.38636139973525 81.37800325481362 L 177.36363860026475 164.8553002461701 L 253.75 70.93785090216556 L 330.1363613997352 208.77160665019417 L 431.1136386002648 102.45398980093603 L 507.5 152.88355990786437 L 583.8863613997353 167.11250164835803 L 684.8636386002647 157.71948768486385 L 761.25 208.63620084646618 L 837.6363613997353 165.34427441671193 L 938.6136386002647 220.79219486386418 L 1015 214.45642412767756" class="register-mean"/>
-    <path d="M 0 229.12306123894965 L 76.38636139973525 379.87811958586695 L 177.36363860026475 361.63841455024703 L 253.75 333.2697839278607 L 330.1363613997352 374.2763468256818 L 431.1136386002648 376.10709741728203 L 507.5 389.06214909783444 L 583.8863613997353 381.32135389237726 L 684.8636386002647 280.0988191788659 L 761.25 294.29830763362236 L 837.6363613997353 331.55885750384425 L 938.6136386002647 311.90261723503045 L 1015 312.0321436872316" class="lookup-mean"/>
-    <circle cx="0" cy="135.24798501632807" r="4" class="register-dot"/>
-    <circle cx="76.38636139973525" cy="81.37800325481362" r="4" class="register-dot"/>
-    <circle cx="177.36363860026475" cy="164.8553002461701" r="4" class="register-dot"/>
-    <circle cx="253.75" cy="70.93785090216556" r="4" class="register-dot"/>
-    <circle cx="330.1363613997352" cy="208.77160665019417" r="4" class="register-dot"/>
-    <circle cx="431.1136386002648" cy="102.45398980093603" r="4" class="register-dot"/>
-    <circle cx="507.5" cy="152.88355990786437" r="4" class="register-dot"/>
-    <circle cx="583.8863613997353" cy="167.11250164835803" r="4" class="register-dot"/>
-    <circle cx="684.8636386002647" cy="157.71948768486385" r="4" class="register-dot"/>
-    <circle cx="761.25" cy="208.63620084646618" r="4" class="register-dot"/>
-    <circle cx="837.6363613997353" cy="165.34427441671193" r="4" class="register-dot"/>
-    <circle cx="938.6136386002647" cy="220.79219486386418" r="4" class="register-dot"/>
-    <circle cx="1015" cy="214.45642412767756" r="4" class="register-dot"/>
-    <circle cx="0" cy="229.12306123894965" r="4" class="lookup-dot"/>
-    <circle cx="76.38636139973525" cy="379.87811958586695" r="4" class="lookup-dot"/>
-    <circle cx="177.36363860026475" cy="361.63841455024703" r="4" class="lookup-dot"/>
-    <circle cx="253.75" cy="333.2697839278607" r="4" class="lookup-dot"/>
-    <circle cx="330.1363613997352" cy="374.2763468256818" r="4" class="lookup-dot"/>
-    <circle cx="431.1136386002648" cy="376.10709741728203" r="4" class="lookup-dot"/>
-    <circle cx="507.5" cy="389.06214909783444" r="4" class="lookup-dot"/>
-    <circle cx="583.8863613997353" cy="381.32135389237726" r="4" class="lookup-dot"/>
-    <circle cx="684.8636386002647" cy="280.0988191788659" r="4" class="lookup-dot"/>
-    <circle cx="761.25" cy="294.29830763362236" r="4" class="lookup-dot"/>
-    <circle cx="837.6363613997353" cy="331.55885750384425" r="4" class="lookup-dot"/>
-    <circle cx="938.6136386002647" cy="311.90261723503045" r="4" class="lookup-dot"/>
-    <circle cx="1015" cy="312.0321436872316" r="4" class="lookup-dot"/>
+    <path d="M 0 162.036023730032 L 76.38636139973525 199.92194454216684 L 177.36363860026475 180.79321863035807 L 253.75 187.60715615722802 L 330.1363613997352 173.91391428005716 L 431.1136386002648 184.06005752352138 L 507.5 141.383386116549 L 583.8863613997353 204.69578214186592 L 684.8636386002647 206.1311970357144 L 761.25 87.08624788584507 L 837.6363613997353 69.96122168468918 L 938.6136386002647 203.07288463701997 L 1015 215.57273165091996" class="register-mean"/>
+    <path d="M 0 364.8039704829771 L 76.38636139973525 379.11430981740193 L 177.36363860026475 284.9534522846775 L 253.75 390.0387783153108 L 330.1363613997352 389.7986492271557 L 431.1136386002648 364.7621485082677 L 507.5 313.9174075959719 L 583.8863613997353 365.8960461378602 L 684.8636386002647 218.5623785529402 L 761.25 182.11371170586403 L 837.6363613997353 272.868648401109 L 938.6136386002647 299.90544804219076 L 1015 308.2620429415109" class="lookup-mean"/>
+    <circle cx="0" cy="162.036023730032" r="4" class="register-dot"/>
+    <circle cx="76.38636139973525" cy="199.92194454216684" r="4" class="register-dot"/>
+    <circle cx="177.36363860026475" cy="180.79321863035807" r="4" class="register-dot"/>
+    <circle cx="253.75" cy="187.60715615722802" r="4" class="register-dot"/>
+    <circle cx="330.1363613997352" cy="173.91391428005716" r="4" class="register-dot"/>
+    <circle cx="431.1136386002648" cy="184.06005752352138" r="4" class="register-dot"/>
+    <circle cx="507.5" cy="141.383386116549" r="4" class="register-dot"/>
+    <circle cx="583.8863613997353" cy="204.69578214186592" r="4" class="register-dot"/>
+    <circle cx="684.8636386002647" cy="206.1311970357144" r="4" class="register-dot"/>
+    <circle cx="761.25" cy="87.08624788584507" r="4" class="register-dot"/>
+    <circle cx="837.6363613997353" cy="69.96122168468918" r="4" class="register-dot"/>
+    <circle cx="938.6136386002647" cy="203.07288463701997" r="4" class="register-dot"/>
+    <circle cx="1015" cy="215.57273165091996" r="4" class="register-dot"/>
+    <circle cx="0" cy="364.8039704829771" r="4" class="lookup-dot"/>
+    <circle cx="76.38636139973525" cy="379.11430981740193" r="4" class="lookup-dot"/>
+    <circle cx="177.36363860026475" cy="284.9534522846775" r="4" class="lookup-dot"/>
+    <circle cx="253.75" cy="390.0387783153108" r="4" class="lookup-dot"/>
+    <circle cx="330.1363613997352" cy="389.7986492271557" r="4" class="lookup-dot"/>
+    <circle cx="431.1136386002648" cy="364.7621485082677" r="4" class="lookup-dot"/>
+    <circle cx="507.5" cy="313.9174075959719" r="4" class="lookup-dot"/>
+    <circle cx="583.8863613997353" cy="365.8960461378602" r="4" class="lookup-dot"/>
+    <circle cx="684.8636386002647" cy="218.5623785529402" r="4" class="lookup-dot"/>
+    <circle cx="761.25" cy="182.11371170586403" r="4" class="lookup-dot"/>
+    <circle cx="837.6363613997353" cy="272.868648401109" r="4" class="lookup-dot"/>
+    <circle cx="938.6136386002647" cy="299.90544804219076" r="4" class="lookup-dot"/>
+    <circle cx="1015" cy="308.2620429415109" r="4" class="lookup-dot"/>
     <!-- Legend -->
     <g transform="translate(20, 20)">
       <rect x="0" y="0" width="190" height="80" fill="white" stroke="#ccc" stroke-width="1"/>
@@ -130,7 +132,7 @@
       <text x="0" y="0" class="metadata-section">System Information</text>
 
       <text x="0" y="25" class="metadata-label">Test Date:</text>
-      <text x="150" y="25" class="metadata-value">2025-07-26</text>
+      <text x="150" y="25" class="metadata-value">2025-07-28</text>
 
       <text x="0" y="45" class="metadata-label">Package Version:</text>
       <text x="150" y="45" class="metadata-value">@fjell/registry v4.4.5</text>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/registry",
   "description": "Dependency injection and service location system for the Fjell ecosystem",
-  "version": "4.4.22",
+  "version": "4.4.24",
   "keywords": [
     "registry",
     "dependency-injection",
@@ -23,7 +23,7 @@
     "dev": "concurrently \"tsc --noEmit --watch\" \"node build.js --watch\"",
     "build": "npm run lint && tsc --noEmit && node build.js",
     "typecheck": "tsc --noEmit",
-    "clean": "rimraf dist",
+    "clean": "rm -rf dist",
     "test": "npm run lint && vitest run --coverage",
     "prepublishOnly": "npm run clean && npm run build",
     "docs:dev": "cd docs && npm run dev",
@@ -48,7 +48,6 @@
     "esbuild": "^0.25.8",
     "eslint": "^9.32.0",
     "jsdom": "^26.1.0",
-    "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
     "vitest": "3.2.4"
   },
@@ -56,4 +55,4 @@
     "type": "git",
     "url": "git+https://github.com/getfjell/registry.git"
   }
-}
+}

package/vitest.config.ts

@@ -1,13 +1,7 @@
 /// <reference types="vitest" />
 import { defineConfig } from 'vitest/config'
-import { resolve } from 'path'
 
 export default defineConfig({
-  resolve: {
-    alias: {
-      '@': resolve(__dirname, './src'),
-    },
-  },
   test: {
     environment: 'jsdom',
     setupFiles: ['./tests/setup.ts'],