@hkdigital/lib-core 0.4.57 → 0.4.58

package/dist/auth/jwt/README.md

@@ -0,0 +1,275 @@
+# JWT Utilities
+
+A comprehensive JSON Web Token (JWT) library for signing, verifying, and 
+decoding JWT tokens with proper error handling and type safety.
+
+## Features
+
+- **Sign tokens** with customizable algorithms and expiration
+- **Verify tokens** with signature validation and expiration checks
+- **Decode payloads** without verification for inspection purposes
+- **Generate secret keys** for HMAC algorithms
+- **Error handling** with specific error types for different failure modes
+- **Type safety** with JSDoc type annotations
+
+## Quick Start
+
+```javascript
+import { sign, verify, decodePayload, expiresAtUTC } from '$lib/auth/jwt.js';
+
+// Create a token
+const payload = { userId: 123, username: 'john' };
+const secret = 'your-secret-key';
+const token = sign(payload, secret);
+
+// Verify and decode
+const decoded = verify(token, secret);
+console.log(decoded.userId); // 123
+
+// Decode without verification (for inspection)
+const payload = decodePayload(token);
+console.log(payload.exp); // expiration timestamp
+
+// Get human-readable expiration
+const expiresAt = expiresAtUTC(payload);
+console.log(expiresAt); // "Sun, 01 Jan 2023 00:00:00 GMT"
+```
+
+## API Reference
+
+### sign(claims, secretOrPrivateKey, options?)
+
+Creates a JSON Web Token with the specified claims.
+
+**Parameters:**
+- `claims` (object) - JWT payload/claims
+- `secretOrPrivateKey` (string|Buffer) - Secret for HMAC or private key
+- `options` (object, optional) - Signing options
+
+**Options:**
+- `algorithm` (string) - Algorithm to use (default: 'HS512')
+- `expiresIn` (string|number) - Token expiration (default: '24h')
+- `issuer` (string) - Token issuer
+- `audience` (string) - Token audience
+- `subject` (string) - Token subject
+
+**Returns:** `string` - JWT token
+
+**Example:**
+```javascript
+const token = sign(
+  { userId: 123, role: 'admin' },
+  'secret-key',
+  { 
+    algorithm: 'HS256',
+    expiresIn: '1h',
+    issuer: 'my-app'
+  }
+);
+```
+
+### verify(token, secretOrPrivateKey, options?)
+
+Verifies and decodes a JWT token.
+
+**Parameters:**
+- `token` (string) - JWT token to verify
+- `secretOrPrivateKey` (string|Buffer) - Secret for HMAC or public key
+- `options` (object, optional) - Verification options
+
+**Options:**
+- `algorithms` (string[]) - Allowed algorithms (default: ['HS512'])
+- `issuer` (string) - Expected issuer
+- `audience` (string) - Expected audience
+- `ignoreExpiration` (boolean) - Skip expiration validation
+
+**Returns:** `object` - Decoded JWT payload
+
+**Throws:**
+- `TokenExpiredError` - Token has expired
+- `InvalidSignatureError` - Invalid signature
+- `JsonWebTokenError` - Other JWT validation errors
+- `NotBeforeError` - Token not yet valid
+
+**Example:**
+```javascript
+try {
+  const decoded = verify(token, 'secret-key');
+  console.log('User ID:', decoded.userId);
+} catch (error) {
+  if (error instanceof TokenExpiredError) {
+    console.log('Token expired at:', error.expiredAt);
+  }
+}
+```
+
+### decodePayload(token)
+
+Decodes JWT payload without verification. Useful for inspecting token claims
+before verification or when verification is not required.
+
+**Parameters:**
+- `token` (string) - JWT token to decode
+
+**Returns:** `object` - Decoded JWT payload
+
+**Throws:**
+- `Error` - Invalid token format or malformed payload
+
+**Example:**
+```javascript
+// Inspect token without verification
+const payload = decodePayload(token);
+console.log('Token expires:', payload.exp);
+console.log('Issued at:', payload.iat);
+
+// Check if token is expired before verification
+if (payload.exp && payload.exp < Date.now() / 1000) {
+  console.log('Token is expired');
+}
+```
+
+### expiresAtUTC(token)
+
+Converts the `exp` claim of a decoded token to a human-readable UTC string.
+
+**Parameters:**
+- `token` (object) - Decoded JWT payload with optional `exp` claim
+
+**Returns:** `string|null` - UTC string or null if no expiration
+
+**Example:**
+```javascript
+const payload = decodePayload(token);
+const expiresAt = expiresAtUTC(payload);
+
+if (expiresAt) {
+  console.log('Token expires at:', expiresAt);
+  // "Sun, 01 Jan 2023 00:00:00 GMT"
+} else {
+  console.log('Token never expires');
+}
+```
+
+## Error Types
+
+The library provides specific error types for different failure modes:
+
+### TokenExpiredError
+Thrown when a token has expired.
+- `message` - Error description
+- `expiredAt` - Date when token expired
+
+### InvalidSignatureError  
+Thrown when token signature is invalid.
+- `message` - Error description
+
+### JsonWebTokenError
+Thrown for general JWT validation errors.
+- `message` - Error description
+
+### NotBeforeError
+Thrown when token is not yet valid (nbf claim).
+- `message` - Error description
+- `date` - Date when token becomes valid
+
+## Security Best Practices
+
+### Secret Key Management
+- Use cryptographically strong secrets (256+ bits for HMAC)
+- Store secrets securely (environment variables, key management services)
+- Rotate secrets regularly
+- Never commit secrets to version control
+
+```javascript
+import { generateSecretKeyForHmacBase58 } from '$lib/auth/jwt.js';
+
+// Generate a secure secret
+const secret = generateSecretKeyForHmacBase58();
+```
+
+### Token Validation
+- Always verify tokens before trusting claims
+- Use specific algorithm allowlists in verification
+- Validate issuer, audience, and other claims as needed
+- Handle expiration appropriately for your use case
+
+```javascript
+const decoded = verify(token, secret, {
+  algorithms: ['HS256'], // Only allow specific algorithms
+  issuer: 'trusted-issuer',
+  audience: 'my-app'
+});
+```
+
+### Token Storage
+- Store tokens securely (httpOnly cookies, secure storage)
+- Use short expiration times when possible
+- Implement token refresh mechanisms
+- Clear tokens on logout
+
+## Common Patterns
+
+### Token Inspection Middleware
+```javascript
+function inspectToken(token) {
+  try {
+    const payload = decodePayload(token);
+    const expiresAt = expiresAtUTC(payload);
+    
+    return {
+      isExpired: payload.exp && payload.exp < Date.now() / 1000,
+      expiresAt,
+      userId: payload.userId,
+      role: payload.role
+    };
+  } catch (error) {
+    return { isValid: false, error: error.message };
+  }
+}
+```
+
+### Token Refresh Check
+```javascript
+function shouldRefreshToken(token) {
+  const payload = decodePayload(token);
+  if (!payload.exp) return false;
+  
+  const now = Date.now() / 1000;
+  const timeUntilExpiry = payload.exp - now;
+  const refreshThreshold = 5 * 60; // 5 minutes
+  
+  return timeUntilExpiry < refreshThreshold && timeUntilExpiry > 0;
+}
+```
+
+### Safe Token Verification
+```javascript
+function safeVerifyToken(token, secret) {
+  try {
+    return { success: true, payload: verify(token, secret) };
+  } catch (error) {
+    return { 
+      success: false, 
+      error: error.constructor.name,
+      message: error.message 
+    };
+  }
+}
+```
+
+## Testing
+
+Run the JWT tests:
+
+```bash
+pnpm test:file src/lib/auth/jwt/
+```
+
+The test suite covers:
+- Token signing with various options
+- Token verification with different scenarios
+- Error handling for expired/invalid tokens
+- Payload decoding without verification
+- UTC time conversion
+- Edge cases and error conditions

package/dist/auth/jwt/util.d.ts

@@ -42,3 +42,19 @@ export function verify(token: string, secretOrPrivateKey: import("./typedef.js")
  * @returns {Error} - The corresponding internal error
  */
 export function castJwtError(error: Error): Error;
+/**
+ * Decodes the payload of a JSON Web Token without verification
+ *
+ * @param {string} token - A JSON Web Token
+ *
+ * @returns {object} claims - The decoded JWT payload
+ */
+export function decodePayload(token: string): object;
+/**
+ * Returns the "exp" (expiresAt) property of a token as UTC string
+ *
+ * @param {object} token - Decoded JWT payload/claims
+ *
+ * @returns {string|null} "expires at" as UTC string or null if no exp claim
+ */
+export function expiresAtUTC(token: object): string | null;

package/dist/auth/jwt/util.js

@@ -144,3 +144,51 @@ export function castJwtError(error) {
   // Return original error if not a known JWT error
   return error;
 }
+
+/**
+ * Decodes the payload of a JSON Web Token without verification
+ *
+ * @param {string} token - A JSON Web Token
+ *
+ * @returns {object} claims - The decoded JWT payload
+ */
+export function decodePayload(token) {
+  expect.notEmptyString(token);
+
+  const firstDot = token.indexOf('.');
+
+  if (firstDot === -1) {
+    throw new Error(
+      'Invalid token, missing [.] token as payload start indicator'
+    );
+  }
+
+  const lastDot = token.lastIndexOf('.');
+
+  if (lastDot === firstDot) {
+    throw new Error(
+      'Invalid token, missing second [.] token as payload end indicator'
+    );
+  }
+
+  const payload = token.slice(firstDot + 1, lastDot);
+
+  return JSON.parse(atob(payload));
+}
+
+/**
+ * Returns the "exp" (expiresAt) property of a token as UTC string
+ *
+ * @param {object} token - Decoded JWT payload/claims
+ *
+ * @returns {string|null} "expires at" as UTC string or null if no exp claim
+ */
+export function expiresAtUTC(token) {
+  expect.object(token);
+
+  if ('exp' in token) {
+    return new Date(1000 * token.exp).toUTCString();
+  }
+
+  return null;
+}

package/dist/auth/jwt.js

@@ -3,7 +3,7 @@
  *
  * @description
  * This module provides a clean API for JWT operations including signing,
- * verifying tokens, and generating secret keys.
+ * verifying tokens, decoding payloads, and generating secret keys.
  */
 
 export * from './jwt/util.js';

package/dist/generic/data/typedef.d.ts

@@ -1,3 +1,4 @@
+export * from "./util/typedef.js";
 declare const _default: {};
 export default _default;
 export type IterableTreeOptions = {

package/dist/generic/data/typedef.js

@@ -6,4 +6,6 @@
  * @property {boolean} outputIntermediateNodes
  */
 
+export * from './util/typedef.js';
+
 export default {};

package/dist/generic/data/util/README.md

@@ -0,0 +1,252 @@
+# Flat Tree Utilities
+
+Tree serialization and deserialization utilities that convert between 
+hierarchical tree structures and flat tree format (ft1).
+
+## Overview
+
+The flat tree utilities provide bidirectional conversion between:
+- **Hierarchical Trees**: Standard nested object structures with children
+- **Flat Tree Format (ft1)**: Compact serialized format with separate 
+  nodes and edges
+
+## Key Features
+
+- **Format Versioning**: ft1 format with forward compatibility
+- **Property Preservation**: Maintains original property names 
+  (`children`, `items`, etc.)
+- **Shared Reference Handling**: Uses WeakMap to track objects that 
+  appear multiple times
+- **ID Collision Avoidance**: No conflicts between user IDs and tree 
+  structure IDs
+- **Efficient Serialization**: Compact flat edge array format
+
+## API Reference
+
+### `buildTree(flatTree, options)`
+
+Converts ft1 flat tree format to hierarchical tree structure.
+
+**Parameters:**
+- `flatTree` - FlatTree object in ft1 format
+- `options` - Optional configuration object
+
+**Returns:** Reconstructed hierarchical tree or null
+
+**Example:**
+```javascript
+import { buildTree } from '$lib/generic/data/util/flat-tree.js';
+
+const flatTree = {
+  format: 'ft1',
+  properties: ['children'],
+  nodes: [
+    { id: 'root', name: 'Root' },
+    { id: 'child1', name: 'Child 1' }
+  ],
+  edges: [0, 0, 1]  // root->children->child1
+};
+
+const hierarchical = buildTree(flatTree);
+// Result: { id: 'root', name: 'Root', children: [{ id: 'child1', name: 'Child 1' }] }
+```
+
+### `flattenTree(hierarchicalTree, options)`
+
+Converts hierarchical tree to ft1 flat tree format.
+
+**Parameters:**
+- `hierarchicalTree` - Nested object structure with children
+- `options` - Optional configuration object
+  - `childrenKey` (default: 'children') - Primary children property name
+
+**Returns:** FlatTree object in ft1 format
+
+**Example:**
+```javascript
+import { flattenTree } from '$lib/generic/data/util/flat-tree.js';
+
+const hierarchical = {
+  id: 'root',
+  name: 'Root',
+  children: [
+    { id: 'child1', name: 'Child 1' }
+  ]
+};
+
+const flatTree = flattenTree(hierarchical);
+// Result: { format: 'ft1', properties: ['children'], nodes: [...], edges: [...] }
+```
+
+## ft1 Format Specification
+
+The ft1 format consists of four main components:
+
+### Format Structure
+
+```javascript
+{
+  format: 'ft1',           // Format version identifier
+  properties: string[],    // Array of property names used in edges
+  nodes: object[],         // Array of node objects (index 0 = root)
+  edges: number[]          // Flat array: [from, prop, to, from, prop, to, ...]
+}
+```
+
+### Properties Array
+
+Maps property indices to names for edge decoding:
+```javascript
+properties: ['children', 'items', 'metadata']
+//           index: 0      1       2
+```
+
+### Nodes Array
+
+Contains node data with children properties removed:
+```javascript
+nodes: [
+  { id: 'root', name: 'Root' },      // index 0 (always root)
+  { id: 'child1', name: 'Child 1' }, // index 1
+  { id: 'item1', name: 'Item 1' }    // index 2
+]
+```
+
+### Edges Array
+
+Flat array in groups of 3: `[from_index, property_index, to_index]`
+```javascript
+edges: [
+  0, 0, 1,  // root(0) -children(0)-> child1(1)
+  0, 1, 2   // root(0) -items(1)-> item1(2)
+]
+```
+
+## Shared Object References
+
+Objects that appear multiple times in the tree are automatically 
+handled using WeakMap tracking:
+
+```javascript
+const sharedNode = { id: 'shared', name: 'Shared' };
+
+const hierarchical = {
+  id: 'root',
+  children: [
+    { id: 'left', children: [sharedNode] },
+    { id: 'right', children: [sharedNode] }  // Same object reference
+  ]
+};
+
+const flattened = flattenTree(hierarchical);
+const rebuilt = buildTree(flattened);
+
+// Shared reference is preserved
+console.log(rebuilt.children[0].children[0] === rebuilt.children[1].children[0]); // true
+```
+
+## Property Detection
+
+The flattening process automatically detects child-containing properties:
+
+```javascript
+const tree = {
+  id: 'root',
+  children: [{ id: 'child1' }],  // Detected as child property
+  items: [{ id: 'item1' }],      // Detected as child property
+  metadata: 'string value'       // Not a child property (ignored)
+};
+```
+
+## Roundtrip Conversion
+
+The utilities maintain data integrity across roundtrip conversions:
+
+```javascript
+const original = { /* complex tree */ };
+const flattened = flattenTree(original);
+const rebuilt = buildTree(flattened);
+const reflattened = flattenTree(rebuilt);
+
+// Data integrity preserved
+console.log(JSON.stringify(flattened) === JSON.stringify(reflattened)); // true
+```
+
+## Error Handling
+
+The utilities provide clear error messages for invalid data:
+
+- **Unsupported format**: When format is not 'ft1'
+- **Invalid edges**: When edges array length is not multiple of 3
+- **Invalid indices**: When node or property indices are out of bounds
+- **Missing data**: When required fields are missing
+
+## Performance Considerations
+
+- **WeakMap Usage**: Efficient object reference tracking
+- **Flat Edge Array**: Compact memory usage for large trees
+- **Property Index Mapping**: Fast property name lookup
+- **No Deep Cloning**: Shallow copies preserve performance
+
+## Use Cases
+
+### Configuration Trees
+```javascript
+const config = {
+  server: {
+    children: [
+      { name: 'port', value: 3000 },
+      { name: 'host', value: 'localhost' }
+    ]
+  }
+};
+```
+
+### File System Trees
+```javascript
+const fileTree = {
+  path: '/',
+  children: [
+    { path: '/src', children: [{ path: '/src/index.js' }] },
+    { path: '/package.json' }
+  ]
+};
+```
+
+### Menu Structures
+```javascript
+const menu = {
+  title: 'Main',
+  items: [
+    { title: 'File', items: [{ title: 'New' }, { title: 'Open' }] },
+    { title: 'Edit', items: [{ title: 'Copy' }, { title: 'Paste' }] }
+  ]
+};
+```
+
+## Migration Guide
+
+### From Legacy Formats
+
+If migrating from older tree formats, ensure your data structure 
+follows these patterns:
+
+1. **Root Object**: Single root node with child properties
+2. **Array Children**: Child properties should be arrays of objects
+3. **Object Structure**: Each node should be a plain object
+4. **No Circular References**: Avoid circular references (use shared 
+   objects instead)
+
+### Type Safety
+
+Use JSDoc type annotations for better development experience:
+
+```javascript
+/**
+ * @param {import('./typedef.js').FlatTree<MyNodeType>} flatTree
+ * @returns {MyNodeType|null}
+ */
+function processTree(flatTree) {
+  return buildTree(flatTree);
+}
+```

package/dist/generic/data/util/flat-tree.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a hierarchical tree from ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {import('./typedef.js').FlatTree<T>} flatTree - Flat tree data
+ *
+ * @returns {T|null} reconstructed hierarchical tree or null
+ */
+export function buildTree<T extends object>(flatTree: import("./typedef.js").FlatTree<T>): T | null;
+/**
+ * Flatten a hierarchical tree into ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {T} hierarchicalTree - Hierarchical tree with nested children
+ *
+ * @returns {import('./typedef.js').FlatTree<T>} flat tree data
+ */
+export function flattenTree<T extends object>(hierarchicalTree: T): import("./typedef.js").FlatTree<T>;

package/dist/generic/data/util/flat-tree.js

@@ -0,0 +1,261 @@
+/* ------------------------------------------------------------------ Imports */
+
+import * as expect from '../../../util/expect.js';
+
+/* ------------------------------------------------------------------ Exports */
+
+/**
+ * Build a hierarchical tree from ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {import('./typedef.js').FlatTree<T>} flatTree - Flat tree data
+ *
+ * @returns {T|null} reconstructed hierarchical tree or null
+ */
+export function buildTree(flatTree) {
+  expect.object(flatTree);
+
+  const { format, properties, nodes, edges } = flatTree;
+
+  if (format !== 'ft1') {
+    throw new Error(`Unsupported format: ${format}. Expected 'ft1'`);
+  }
+
+  if (!nodes || !nodes.length) {
+    return null;
+  }
+
+  if (!edges || !edges.length) {
+    return { ...nodes[0] };
+  }
+
+  if (edges.length % 3 !== 0) {
+    throw new Error('Invalid edges array: length must be multiple of 3');
+  }
+
+  // Create copies of all nodes to avoid mutating original data
+  const nodesCopy = nodes.map(node => ({ ...node }));
+
+  // Process edges in groups of 3: [from, prop, to]
+  for (let i = 0; i < edges.length; i += 3) {
+    const fromIndex = edges[i];
+    const propIndex = edges[i + 1];
+    const toIndex = edges[i + 2];
+
+    // Validate indices
+    if (fromIndex >= nodesCopy.length || toIndex >= nodesCopy.length) {
+      throw new Error(`Invalid node index in edge [${fromIndex}, ${propIndex}, ${toIndex}]`);
+    }
+
+    if (propIndex >= properties.length) {
+      throw new Error(`Invalid property index: ${propIndex}`);
+    }
+
+    const fromNode = nodesCopy[fromIndex];
+    const toNode = nodesCopy[toIndex];
+    const propertyName = properties[propIndex];
+
+    // Add child to parent's property
+    /** @type {any} */
+    const dynamicFromNode = fromNode;
+
+    if (!dynamicFromNode[propertyName]) {
+      dynamicFromNode[propertyName] = [toNode];
+    } else if (Array.isArray(dynamicFromNode[propertyName])) {
+      // Check if this node is already in the array (shared reference)
+      if (!dynamicFromNode[propertyName].includes(toNode)) {
+        dynamicFromNode[propertyName].push(toNode);
+      }
+    } else {
+      // Convert single child to array
+      dynamicFromNode[propertyName] = [dynamicFromNode[propertyName], toNode];
+    }
+  }
+
+  return nodesCopy[0];
+}
+
+/**
+ * Flatten a hierarchical tree into ft1 flat tree format
+ *
+ * @template {object} T
+ * @param {T} hierarchicalTree - Hierarchical tree with nested children
+ *
+ * @returns {import('./typedef.js').FlatTree<T>} flat tree data
+ */
+export function flattenTree(hierarchicalTree) {
+  expect.object(hierarchicalTree);
+
+  /** @type {T[]} */
+  const nodes = [];
+  
+  /** @type {number[]} */
+  const edges = [];
+  
+  /** @type {Set<string>} */
+  const propertySet = new Set();
+  
+  /** @type {WeakMap<object, number>} */
+  const objectToIndex = new WeakMap();
+
+  // First pass: collect all child-containing properties
+  const childProperties = new Set();
+  findChildProperties(hierarchicalTree, childProperties);
+
+  // Add root node (always index 0)
+  const rootCopy = extractNodeData(hierarchicalTree, childProperties);
+  nodes.push(rootCopy);
+  objectToIndex.set(hierarchicalTree, 0);
+
+  // Process children recursively
+  processChildrenFt1(
+    hierarchicalTree,
+    0,
+    nodes,
+    edges,
+    propertySet,
+    objectToIndex,
+    childProperties
+  );
+
+  // Convert property set to sorted array for consistent output
+  const properties = Array.from(propertySet).sort();
+
+  // Convert property names to indices in edges array
+  for (let i = 1; i < edges.length; i += 3) {
+    const propertyName = /** @type {string} */ (edges[i]);
+    edges[i] = properties.indexOf(propertyName);
+  }
+
+  return /** @type {import('./typedef.js').FlatTree<T>} */ ({
+    format: 'ft1',
+    properties,
+    nodes,
+    edges
+  });
+}
+
+/* ---------------------------------------------------------- Private methods */
+
+/**
+ * Extract node data excluding children properties
+ *
+ * @param {object} node - Source node
+ * @param {Set<string>} propertiesToRemove - Set of property names to remove
+ *
+ * @returns {object} node data without children properties
+ */
+function extractNodeData(node, propertiesToRemove) {
+  /** @type {any} */
+  const nodeData = { ...node };
+
+  // Remove all child-containing properties
+  for (const key of propertiesToRemove) {
+    delete nodeData[key];
+  }
+
+  return nodeData;
+}
+
+/**
+ * Find all properties that contain child objects
+ *
+ * @param {object} node - Node to analyze
+ * @param {Set<string>} childProperties - Set to collect property names
+ */
+function findChildProperties(node, childProperties) {
+  // Find array properties that contain objects (potential children)
+  for (const [key, value] of Object.entries(node)) {
+    if (Array.isArray(value) && value.length > 0) {
+      // Check if array contains objects (potential children)
+      const hasObjects = value.some(item => item && typeof item === 'object');
+      if (hasObjects) {
+        childProperties.add(key);
+      }
+    }
+  }
+
+  // Recursively check child nodes
+  for (const key of [...childProperties]) {  // Copy set to avoid modification during iteration
+    const children = node[key];
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child && typeof child === 'object') {
+          findChildProperties(child, childProperties);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Recursively process children for ft1 format
+ *
+ * @param {object} parentNode - Parent node with children
+ * @param {number} parentIndex - Parent node index
+ * @param {object[]} nodes - Nodes array to populate
+ * @param {(number|string)[]} edges - Edges array to populate (mixed types temporarily)
+ * @param {Set<string>} propertySet - Set of property names
+ * @param {WeakMap<object, number>} objectToIndex - Map of objects to indices
+ * @param {Set<string>} childProperties - Set of all child-containing properties
+ */
+function processChildrenFt1(parentNode, parentIndex, nodes, edges, propertySet, objectToIndex, childProperties) {
+  // Process all child-containing properties
+  for (const property of childProperties) {
+    const children = parentNode[property];
+    
+    if (!children) {
+      continue;
+    }
+    
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child && typeof child === 'object') {
+          processChildFt1(child, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties);
+        }
+      }
+    } else if (children && typeof children === 'object') {
+      processChildFt1(children, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties);
+    }
+  }
+}
+
+/**
+ * Process a single child node for ft1 format
+ *
+ * @param {object} child - Child node
+ * @param {number} parentIndex - Parent node index
+ * @param {string} property - Property name where this child belongs
+ * @param {object[]} nodes - Nodes array to populate
+ * @param {(number|string)[]} edges - Edges array to populate (mixed types temporarily)
+ * @param {Set<string>} propertySet - Set of property names
+ * @param {WeakMap<object, number>} objectToIndex - Map of objects to indices
+ * @param {Set<string>} childProperties - Set of all child-containing properties
+ */
+function processChildFt1(child, parentIndex, property, nodes, edges, propertySet, objectToIndex, childProperties) {
+  if (!child || typeof child !== 'object') {
+    return;
+  }
+
+  // Track property name
+  propertySet.add(property);
+
+  // Check if we've seen this object before
+  let childIndex = objectToIndex.get(child);
+  
+  if (childIndex === undefined) {
+    // First time seeing this object - add it to nodes
+    childIndex = nodes.length;
+    const childCopy = extractNodeData(child, childProperties);
+    nodes.push(childCopy);
+    objectToIndex.set(child, childIndex);
+  }
+
+  // Add edge (temporarily store property name as string, will convert to index later)
+  edges.push(parentIndex, property, childIndex);
+  
+  // If this is a new object, recursively process its children
+  if (objectToIndex.get(child) === childIndex) {
+    processChildrenFt1(child, childIndex, nodes, edges, propertySet, objectToIndex, childProperties);
+  }
+}

package/dist/generic/data/util/typedef.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Flat tree data structure in ft1 format
+ */
+export type FlatTree<T extends object> = {
+    /**
+     * - Format version ('ft1')
+     */
+    format: string;
+    /**
+     * - Array of property names used in edges
+     */
+    properties: string[];
+    /**
+     * - Array of node objects (index 0 = root)
+     */
+    nodes: T[];
+    /**
+     * - Flat array: [from, prop, to, from, prop, to, ...]
+     */
+    edges: number[];
+};

package/dist/generic/data/util/typedef.js

@@ -0,0 +1,14 @@
+/* ------------------------------------------------------------------ Typedef */
+
+/**
+ * Flat tree data structure in ft1 format
+ *
+ * @template {object} T
+ * @typedef {object} FlatTree
+ * @property {string} format - Format version ('ft1')
+ * @property {string[]} properties - Array of property names used in edges
+ * @property {T[]} nodes - Array of node objects (index 0 = root)
+ * @property {number[]} edges - Flat array: [from, prop, to, from, prop, to, ...]
+ */
+
+export {};

package/dist/generic/data.d.ts

@@ -1,2 +1,3 @@
 export { default as Selector } from "./data/classes/Selector.js";
 export { default as IterableTree } from "./data/classes/IterableTree.js";
+export { buildTree, flattenTree } from "./data/util/flat-tree.js";

package/dist/generic/data.js

@@ -1,2 +1,3 @@
 export { default as Selector } from './data/classes/Selector.js';
 export { default as IterableTree } from './data/classes/IterableTree.js';
+export { buildTree, flattenTree } from './data/util/flat-tree.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.57",
+	"version": "0.4.58",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"