dbl-utils
Version:
Utilities for dbl, adba and others projects
191 lines (190 loc) • 7.2 kB
TypeScript
import type { ResolveRefsRules, ResolveRefsTasks, ResolvableValue } from "./types";
/**
* Resolve references within objects and arrays using advanced reference resolution.
*
* This powerful utility enables dynamic object composition through multiple reference types:
* global references, relative references, string interpolation, and template inheritance.
* Perfect for configuration management, dynamic content generation, and object templating.
*
* @param object - The source object or array containing references to resolve.
* References use `$path/to/value` syntax for global lookups or
* `$./path` for relative references.
* @param schema - Schema object used as the base for global reference lookups.
* If not provided, uses a deep clone of the source object.
* This is where `$path/to/value` references are resolved against.
* @param rules - Custom rule definitions for advanced reference processing.
* Each rule maps a reference key to a tuple `[taskName, ...args]`.
* Built-in tasks: 'iterate', 'join', 'ignore', 'if'.
* @param extraTasks - Additional custom task functions that can be used in rules.
* Each task receives the resolved arguments and should return a value.
* @returns A new object with all references resolved and templates expanded.
*
* ## Reference Types
*
* ### 1. Global References
* Reference values anywhere in the schema using absolute paths:
* - `"$path/to/value"` - Direct reference to a value
* - `"${path/to/value}"` - String interpolation (embeds value in string)
* - `"prefix-${path/to/value}-suffix"` - Mixed string with interpolated values
*
* ### 2. Object Template References
* Extend and modify referenced objects:
* - `{ ref: "$path/to/template", newProp: "value" }` - Template inheritance
* - `{ ref: "path/to/template", existingProp: "override" }` - Property override
*
* ### 3. Relative References
* Reference values within the current object context:
* - `"$./property"` - Direct relative reference
* - `"${./nested/property}"` - Relative string interpolation
* - `"${./path}-${./other}"` - Multiple relative references in strings
*
* ### 4. Template System with Deferred Resolution
* Use the special `"."` key for references resolved after template merging:
* - `"."` object contains references processed after base template + overrides
* - Enables templates to reference their final merged state
* - Supports recursive resolution until stable state is reached
*
* ## Advanced Features
*
* ### Custom Rules and Tasks
* Define reusable logic for complex transformations:
* ```ts
* const rules = {
* "$users": ["iterate", "$data/users", "currentUser"],
* "$joinNames": ["join", "$people", ", ", "$extraPeople"]
* };
*
* const extraTasks = {
* uppercase: (value: string) => value.toUpperCase(),
* calculate: (a: number, b: number) => a + b
* };
* ```
*
* ### Built-in Tasks
* - `iterate(array, itemName)` - Process array items with template
* - `join(array, separator, ...extra)` - Join arrays with separator
* - `ignore(path, fallback)` - Safe lookup with fallback
* - `if(condition, trueValue, falseValue)` - Conditional resolution
*
* @example
* Basic global references:
* ```ts
* const config = { api: { url: "https://api.com", key: "abc123" } };
* const settings = { endpoint: "$api/url", auth: "Bearer ${api/key}" };
*
* const result = resolveRefs(settings, config);
* // { endpoint: "https://api.com", auth: "Bearer abc123" }
* ```
*
* @example
* Template inheritance with property overrides:
* ```ts
* const data = {
* defaultUser: { name: "Guest", role: "viewer", active: false },
* admin: { ref: "$defaultUser", name: "Admin", role: "admin", active: true },
* viewer: { ref: "$defaultUser", name: "John" }
* };
*
* const result = resolveRefs(data);
* // result.admin = { name: "Admin", role: "admin", active: true }
* // result.viewer = { name: "John", role: "viewer", active: false }
* ```
*
* @example
* Relative references with template system:
* ```ts
* const data = {
* user1: { ref: "$templates/user", firstName: "Alice", lastName: "Smith" },
* user2: { ref: "$templates/user", firstName: "Bob", lastName: "Jones" },
* templates: {
* user: {
* firstName: "",
* lastName: "",
* email: "",
* ".": {
* fullName: "${./firstName} ${./lastName}",
* email: "${./firstName}.${./lastName}@company.com",
* profile: {
* displayName: "$./fullName",
* username: "$./firstName"
* }
* }
* }
* }
* };
*
* const result = resolveRefs(data);
* // result.user1.fullName = "Alice Smith"
* // result.user1.email = "Alice.Smith@company.com"
* // result.user1.profile.displayName = "Alice Smith"
* ```
*
* @example
* Configuration management with mixed references:
* ```ts
* const config = {
* env: { baseUrl: "https://api.prod.com", version: "v2" },
* services: {
* auth: { ref: "$templates/service", path: "/auth", timeout: 5000 },
* users: { ref: "$templates/service", path: "/users", timeout: 3000 }
* },
* templates: {
* service: {
* path: "/",
* timeout: 30000,
* retries: 3,
* ".": {
* url: "${env/baseUrl}/${env/version}${./path}",
* config: {
* endpoint: "$./url",
* timeout: "$./timeout",
* retries: "$./retries"
* }
* }
* }
* }
* };
*
* const result = resolveRefs(config);
* // result.services.auth.url = "https://api.prod.com/v2/auth"
* // result.services.auth.config.endpoint = "https://api.prod.com/v2/auth"
* ```
*
* @example
* Custom rules and tasks:
* ```ts
* const data = { users: ["Alice", "Bob"], items: [1, 2, 3] };
* const template = {
* userList: "$buildUserList",
* summary: "$joinItems"
* };
*
* const rules = {
* "$buildUserList": ["iterate", "$users", "user"],
* "$joinItems": ["join", "$items", " + "]
* };
*
* const extraTasks = {
* format: (template: string, ...values: any[]) =>
* template.replace(/{(\d+)}/g, (_, i) => values[i])
* };
*
* const result = resolveRefs(template, data, rules, extraTasks);
* ```
*
* ## Best Practices
*
* 1. **Schema Organization**: Keep templates in a dedicated section (e.g., `templates/`)
* 2. **Reference Clarity**: Use descriptive paths like `config/database/url` vs `c/d/u`
* 3. **Template Design**: Use relative references in `"."` for dynamic template properties
* 4. **Performance**: Avoid deep circular references that could cause infinite loops
* 5. **Type Safety**: Consider using TypeScript interfaces for your schema structure
*
* ## Error Handling
*
* - Invalid references return the original reference string
* - Missing paths in schema return `undefined`
* - Circular references are prevented through iteration limits
* - Type mismatches in string interpolation are converted to strings
*/
export default function resolveRefs<T = any>(object: ResolvableValue, schema?: Record<string, any>, rules?: ResolveRefsRules, extraTasks?: ResolveRefsTasks): T;