@player-tools/fluent 0.13.0--canary.221.5662

package/src/core/base-builder/id/generator.ts

@@ -0,0 +1,286 @@
+import { globalIdRegistry } from "./registry";
+import type { AssetMetadata, BaseBuildContext } from "../types";
+
+export { globalIdRegistry, createIdRegistry, IDRegistry } from "./registry";
+
+/**
+ * Resets the global ID registry, clearing all registered IDs.
+ * This is useful for testing scenarios where you need a clean slate.
+ */
+export const resetGlobalIdSet = (): void => {
+  globalIdRegistry.reset();
+};
+
+/**
+ * Internal function that generates a base ID from context without registry operations.
+ * This is the core ID generation logic shared between peekId and genId.
+ *
+ * @param context - The context containing parent ID and optional branch information
+ * @param functionName - The name of the calling function (for error messages)
+ * @returns The generated base ID
+ */
+const _generateBaseId = (
+  context: BaseBuildContext,
+  functionName: string,
+): string => {
+  // Validate context
+  if (!context) {
+    throw new Error(
+      `${functionName}: Context is undefined. Please provide a valid BaseBuildContext object.`,
+    );
+  }
+
+  const { parentId, branch } = context;
+
+  let baseId: string;
+
+  if (!branch) {
+    baseId = parentId || "";
+  } else {
+    switch (branch.type) {
+      case "custom":
+        baseId = parentId || "";
+        break;
+
+      case "slot":
+        if (!branch.name) {
+          throw new Error(
+            `${functionName}: Slot branch requires a 'name' property. ` +
+              `Context: ${JSON.stringify(context)}`,
+          );
+        }
+        baseId = `${parentId ? `${parentId}-` : ""}${branch.name}`;
+        break;
+
+      case "array-item":
+        if (typeof branch.index !== "number") {
+          throw new Error(
+            `${functionName}: Array-item branch requires a numeric 'index' property. ` +
+              `Got: ${typeof branch.index}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        if (branch.index < 0) {
+          throw new Error(
+            `${functionName}: Array-item index must be non-negative. ` +
+              `Got: ${branch.index}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        baseId = `${parentId}-${branch.index}`;
+        break;
+
+      case "template":
+        if (branch.depth !== undefined && branch.depth < 0) {
+          throw new Error(
+            `${functionName}: Template depth must be non-negative. ` +
+              `Got: ${branch.depth}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        baseId = `${parentId}-_index${branch.depth || ""}_`;
+        break;
+
+      case "switch":
+        if (typeof branch.index !== "number") {
+          throw new Error(
+            `${functionName}: Switch branch requires a numeric 'index' property. ` +
+              `Got: ${typeof branch.index}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        if (branch.index < 0) {
+          throw new Error(
+            `${functionName}: Switch index must be non-negative. ` +
+              `Got: ${branch.index}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        if (!branch.kind || !["static", "dynamic"].includes(branch.kind)) {
+          throw new Error(
+            `${functionName}: Switch branch requires 'kind' to be 'static' or 'dynamic'. ` +
+              `Got: ${branch.kind}. Context: ${JSON.stringify(context)}`,
+          );
+        }
+        baseId = `${parentId}-${branch.kind}Switch-${branch.index}`;
+        break;
+
+      default: {
+        const exhaustiveCheck: never = branch;
+        throw new Error(
+          `${functionName}: Unhandled branch type: ${JSON.stringify(exhaustiveCheck)}`,
+        );
+      }
+    }
+  }
+
+  return baseId;
+};
+
+/**
+ * Generates an ID without registering it in the global registry.
+ * This is useful for intermediate ID lookups where you don't want to consume the ID.
+ *
+ * @param context - The context containing parent ID and optional branch information
+ * @returns The generated ID (without collision detection or registration)
+ *
+ * @example
+ * // Use this when you need to generate a parent ID for nested context creation
+ * const parentId = peekId({ parentId: 'collection' }); // Doesn't register 'collection'
+ * const nestedCtx = { parentId, branch: { type: 'slot', name: 'label' } };
+ */
+export const peekId = (context: BaseBuildContext): string => {
+  return _generateBaseId(context, "peekId");
+};
+
+/**
+ * Generates a unique identifier based on the parent ID and branch information.
+ *
+ * This function creates hierarchical IDs for various element types in a DSL structure,
+ * maintaining relationships between parent and child elements through consistent naming patterns.
+ * IDs are automatically checked for uniqueness and modified if collisions are detected.
+ *
+ * @param {BaseBuildContext} context - The context containing parent ID and optional branch information
+ * @param {string} context.parentId - The ID of the parent element
+ * @param {IdBranch} [context.branch] - Optional branch information to specify the type of child element
+ *
+ * @returns {string} A generated ID string representing the element's unique identifier
+ *
+ * @throws {Error} If context is invalid or incomplete
+ *
+ * @example
+ * // Slot branch
+ * genId({ parentId: 'parent', branch: { type: 'slot', name: 'header' } })
+ * // Returns: 'parent-header'
+ *
+ * @example
+ * // Array item branch
+ * genId({ parentId: 'list', branch: { type: 'array-item', index: 2 } })
+ * // Returns: 'list-2'
+ *
+ * @example
+ * // Template branch
+ * genId({ parentId: 'template', branch: { type: 'template', depth: 1 } })
+ * // Returns: 'template-_index1_'
+ *
+ * @example
+ * // Switch branch
+ * genId({ parentId: 'condition', branch: { type: 'switch', index: 0, kind: 'static' } })
+ * // Returns: 'condition-staticSwitch-0'
+ *
+ * @example
+ * // Custom ID case (no branch)
+ * genId({ parentId: 'custom-id' })
+ * // Returns: 'custom-id'
+ */
+export const genId = (context: BaseBuildContext): string => {
+  const baseId = _generateBaseId(context, "genId");
+
+  const { parentId, branch } = context;
+
+  if (!parentId && !branch) {
+    console.warn(
+      "genId: Context appears incomplete (no parentId or branch). " +
+        "This may result in an empty or invalid ID. " +
+        "Consider using context helper functions from 'fluent/utils/context'.",
+    );
+  }
+
+  if (parentId === "") {
+    console.warn(
+      "genId: parentId is an empty string. " +
+        "This may indicate a missing or improperly initialized context.",
+    );
+  }
+
+  // Ensure the generated ID is unique
+  const uniqueId = globalIdRegistry.ensureUnique(baseId);
+
+  // Warn if collision was detected
+  if (process.env.NODE_ENV !== "production" && uniqueId !== baseId) {
+    console.warn(
+      `genId: ID collision detected. Original: "${baseId}", Modified to: "${uniqueId}". ` +
+        `Consider providing more specific IDs to avoid collisions.`,
+    );
+  }
+
+  return uniqueId;
+};
+
+export function determineSlotName(
+  parameterName: string,
+  assetMetadata?: AssetMetadata,
+): string {
+  if (!assetMetadata) {
+    return parameterName;
+  }
+
+  const { type, binding, value } = assetMetadata;
+
+  // Rule 1: If the asset type is `action`, append last segment of `value` if any
+  // Note: value can be a binding (TaggedTemplateValue) or plain string
+  if (type === "action" && value) {
+    const cleanValue = value.replace(/^\{\{|\}\}$/g, "");
+    const segments = cleanValue.split(".");
+    const lastSegment = segments[segments.length - 1];
+    return lastSegment ? `${type}-${lastSegment}` : type;
+  }
+
+  // Rule 2: If it's not `action` but has `binding`, append last fragment of binding
+  if (type !== "action" && binding) {
+    const cleanBinding = binding.replace(/^\{\{|\}\}$/g, "");
+    const segments = cleanBinding.split(".");
+    const lastSegment = segments[segments.length - 1];
+    if (lastSegment) {
+      return `${type || parameterName}-${lastSegment}`;
+    }
+  }
+
+  // Rule 3: Otherwise, just use the type
+  return type || parameterName;
+}
+
+export function generateAssetId<C extends BaseBuildContext>(params: {
+  readonly context?: C;
+  readonly parameterName?: string;
+  readonly assetMetadata?: AssetMetadata;
+  readonly explicitId?: string;
+}): string {
+  const {
+    context,
+    parameterName = "asset",
+    assetMetadata,
+    explicitId,
+  } = params;
+
+  if (explicitId) {
+    return explicitId;
+  }
+
+  if (context && "parentId" in context) {
+    // Determine the slot name based on asset metadata (action value, binding, or type)
+    const slotName = determineSlotName(parameterName, assetMetadata);
+
+    if (context.branch) {
+      // When there's a branch, generate base ID then append asset type
+      // This creates IDs like "parent-0-questionAnswer", "parent-slot-text", etc.
+      const baseId = genId(context);
+
+      // Append the asset type as a suffix
+      // Use genId again to ensure uniqueness and proper registration
+      return genId({
+        ...context,
+        parentId: baseId,
+        branch: { type: "slot", name: slotName },
+      } as C);
+    }
+
+    if (context.parentId) {
+      // When there's a parentId but no branch, use slotName (determined from metadata)
+      // This creates IDs like "parent-text", "parent-action-next", "parent-input-firstName", etc.
+      // Generate and register the ID to enable collision detection
+      return genId({
+        ...context,
+        branch: { type: "slot", name: slotName },
+      } as C);
+    }
+  }
+
+  const slotName = determineSlotName(parameterName, assetMetadata);
+  return slotName;
+}

package/src/core/base-builder/id/registry.ts

@@ -0,0 +1,152 @@
+/**
+ * ID Registry for tracking and ensuring unique IDs across asset generation.
+ * This registry maintains a set of used IDs and provides collision resolution
+ * by appending numeric suffixes when duplicates are detected.
+ *
+ * Special handling for template placeholders:
+ * - IDs ending with template placeholders like `_index_`, `_row_` are allowed to be duplicated
+ * - IDs with placeholders followed by additional segments enforce uniqueness normally
+ */
+export class IDRegistry {
+  private usedIds: Set<string>;
+  private isEnabled: boolean;
+
+  constructor(enabled = true) {
+    this.usedIds = new Set<string>();
+    this.isEnabled = enabled;
+  }
+
+  /**
+   * Ensures the given ID is unique, modifying it if necessary.
+   * If the ID already exists, appends a numeric suffix (-1, -2, etc.)
+   * until a unique ID is found.
+   *
+   * Special handling for template placeholders:
+   * - IDs ending with `_index_`, `_row_`, etc. are allowed as duplicates
+   * - IDs with placeholders followed by segments (e.g., `_index_.field`) enforce uniqueness
+   *
+   * @param baseId - The desired ID
+   * @returns A unique ID (either the original or modified with suffix)
+   *
+   * @example
+   * ```typescript
+   * const registry = new IDRegistry();
+   * registry.ensureUnique("my-id");         // "my-id"
+   * registry.ensureUnique("my-id");         // "my-id-1"
+   * registry.ensureUnique("list-_index_");  // "list-_index_" (allowed duplicate)
+   * registry.ensureUnique("list-_index_");  // "list-_index_" (allowed duplicate)
+   * ```
+   */
+  ensureUnique(baseId: string): string {
+    // If registry is disabled, return the ID as-is
+    if (!this.isEnabled) {
+      return baseId;
+    }
+
+    // Check if this ID contains template placeholders
+    if (this.isTemplatePlaceholderID(baseId)) {
+      // For template placeholder IDs, don't enforce uniqueness
+      // These will be replaced at runtime, so duplicates are acceptable
+      return baseId;
+    }
+
+    // If the ID hasn't been used, register and return it
+    if (!this.usedIds.has(baseId)) {
+      this.usedIds.add(baseId);
+      return baseId;
+    }
+
+    // ID collision detected - append counter until unique
+    let counter = 1;
+    let uniqueId = `${baseId}-${counter}`;
+
+    while (this.usedIds.has(uniqueId)) {
+      counter++;
+      uniqueId = `${baseId}-${counter}`;
+    }
+
+    this.usedIds.add(uniqueId);
+    return uniqueId;
+  }
+
+  /**
+   * Checks if an ID has already been used.
+   *
+   * @param id - The ID to check
+   * @returns true if the ID has been used, false otherwise
+   */
+  has(id: string): boolean {
+    return this.usedIds.has(id);
+  }
+
+  /**
+   * Clears all registered IDs from the registry.
+   * Useful for resetting state between test runs or separate flows.
+   */
+  reset(): void {
+    this.usedIds.clear();
+  }
+
+  /**
+   * Enables or disables the uniqueness checking.
+   * When disabled, all IDs pass through unchanged.
+   *
+   * @param enabled - Whether to enable uniqueness checking
+   */
+  setEnabled(enabled: boolean): void {
+    this.isEnabled = enabled;
+  }
+
+  /**
+   * Returns the number of unique IDs currently registered.
+   *
+   * @returns The count of registered IDs
+   */
+  size(): number {
+    return this.usedIds.size;
+  }
+
+  /**
+   * Returns a snapshot of all registered IDs.
+   * Useful for debugging and testing.
+   *
+   * @returns An array of all registered IDs
+   */
+  getRegisteredIds(): string[] {
+    return Array.from(this.usedIds);
+  }
+
+  /**
+   * Checks if an ID contains template placeholders that should be exempt from uniqueness checks.
+   * Template placeholders are patterns like `_index_`, `_index1_`, `_row_` that are replaced at runtime.
+   *
+   * IDs ending with just a placeholder (e.g., "parent-_index_") are allowed as duplicates.
+   * IDs with placeholders followed by additional segments (e.g., "parent-_index_-field") are not.
+   *
+   * @param id - The ID to check
+   * @returns true if the ID should be exempt from uniqueness checks
+   */
+  private isTemplatePlaceholderID(id: string): boolean {
+    // Pattern to match template placeholder at the end of an ID
+    // Matches: _index_, _index1_, _row_, _item_, etc. at the end of the string
+    const templatePlaceholderPattern = /_(?:index|row|item)\d*_$/;
+    return templatePlaceholderPattern.test(id);
+  }
+}
+
+/**
+ * Global singleton instance of the ID registry.
+ * This ensures consistent ID tracking across the entire application.
+ */
+export const globalIdRegistry: IDRegistry = new IDRegistry();
+
+/**
+ * Creates a new isolated ID registry instance.
+ * Useful for testing or when you need separate ID tracking contexts.
+ *
+ * @param enabled - Whether the registry should be enabled by default
+ * @returns A new IDRegistry instance
+ */
+export function createIdRegistry(enabled = true): IDRegistry {
+  return new IDRegistry(enabled);
+}

package/src/core/base-builder/index.ts

@@ -0,0 +1,60 @@
+export {
+  FLUENT_BUILDER_SYMBOL,
+  type NestedContextParams,
+  type NestedContextGenerator,
+  type AssetMetadata,
+  type BaseBuildContext,
+  type FluentBuilder,
+  type AnyAssetBuilder,
+  type MixedArrayMetadata,
+  type TemplateMetadata,
+  type IdBranch,
+  type SlotBranch,
+  type ArrayItemBranch,
+  type TemplateBranch,
+  type SwitchBranch,
+  type CustomBranch,
+  type ValuePath,
+  type SwitchMetadata,
+  type ConditionalValue,
+} from "./types";
+
+export {
+  isFluentBuilder,
+  isBuilderArray,
+  isPlainObject,
+  isAsset,
+  isAssetWrapper,
+  isAssetWrapperWithAsset,
+  needsAssetWrapper,
+  isAssetWrapperValue,
+  isSwitchResult,
+  isStringOrUndefined,
+} from "./guards";
+
+export {
+  determineSlotName,
+  generateAssetId,
+  genId,
+  peekId,
+  resetGlobalIdSet,
+  globalIdRegistry,
+  createIdRegistry,
+  IDRegistry,
+} from "./id/generator";
+
+export {
+  createNestedContext,
+  createTemplateContext,
+  createSwitchContext,
+} from "./context";
+
+export {
+  extractValue,
+  resolveValue,
+  resolveAndWrapAsset,
+} from "./resolution/value-resolver";
+
+export { FluentBuilderBase } from "./fluent-builder-base";
+
+export { createInspectMethod } from "./utils";

package/src/core/base-builder/resolution/path-resolver.ts

@@ -0,0 +1,108 @@
+import type { ValuePath } from "../types";
+import { isAssetWrapperValue } from "../guards";
+
+/**
+ * Sets a value at a nested path in an object
+ * Handles nested objects, arrays, and AssetWrapper structures
+ *
+ * @param obj - The target object to modify
+ * @param path - Array of keys/indices representing the path
+ * @param value - The value to set at the path
+ *
+ * @example
+ * setValueAtPath(obj, ["actions", 0, "label"], "Click me")
+ * // Sets obj.actions[0].label = "Click me"
+ */
+export function setValueAtPath(
+  obj: Record<string, unknown>,
+  path: ValuePath,
+  value: unknown,
+): void {
+  if (path.length === 0) return;
+
+  if (path.length === 1) {
+    obj[path[0]] = value;
+    return;
+  }
+
+  const [currentKey, ...restPath] = path;
+  const nextKey = restPath[0];
+  const currentValue = obj[currentKey];
+
+  // Check if current value is an AssetWrapper containing an array
+  const isAssetWrapperWithArray =
+    isAssetWrapperValue(currentValue) && Array.isArray(currentValue.asset);
+
+  if (isAssetWrapperWithArray && typeof nextKey === "number") {
+    setValueInAssetWrapperArray(
+      obj,
+      currentKey,
+      currentValue as { asset: unknown[] },
+      nextKey,
+      restPath,
+      value,
+    );
+  } else if (Array.isArray(currentValue) && typeof nextKey === "number") {
+    setValueInArray(obj, currentKey, currentValue, nextKey, restPath, value);
+  } else {
+    setValueInObject(obj, currentKey, restPath, value);
+  }
+}
+
+/**
+ * Sets value in an array within an AssetWrapper
+ */
+function setValueInAssetWrapperArray(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  wrappedArray: { asset: unknown[] },
+  nextKey: number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const arrayResult = [...wrappedArray.asset];
+  if (restPath.length === 1) {
+    arrayResult[nextKey] = value;
+  } else {
+    const nestedObj = (arrayResult[nextKey] as Record<string, unknown>) ?? {};
+    setValueAtPath(nestedObj, restPath.slice(1), value);
+    arrayResult[nextKey] = nestedObj;
+  }
+  obj[currentKey] = { asset: arrayResult };
+}
+
+/**
+ * Sets value in a regular array
+ */
+function setValueInArray(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  array: unknown[],
+  nextKey: number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const arrayResult = [...array];
+  if (restPath.length === 1) {
+    arrayResult[nextKey] = value;
+  } else {
+    const nestedObj = (arrayResult[nextKey] as Record<string, unknown>) ?? {};
+    setValueAtPath(nestedObj, restPath.slice(1), value);
+    arrayResult[nextKey] = nestedObj;
+  }
+  obj[currentKey] = arrayResult;
+}
+
+/**
+ * Sets value in a nested object
+ */
+function setValueInObject(
+  obj: Record<string, unknown>,
+  currentKey: string | number,
+  restPath: ValuePath,
+  value: unknown,
+): void {
+  const nestedObj = (obj[currentKey] as Record<string, unknown>) ?? {};
+  setValueAtPath(nestedObj, restPath, value);
+  obj[currentKey] = nestedObj;
+}

package/src/core/base-builder/resolution/pipeline.ts

@@ -0,0 +1,96 @@
+import type { BaseBuildContext } from "../types";
+import type { ValueStorage } from "../storage/value-storage";
+import type { AuxiliaryStorage } from "../storage/auxiliary-storage";
+import { resolveStaticValues } from "./steps/static-values";
+import { generateAssetIdForBuilder } from "./steps/asset-id";
+import { resolveAssetWrappers } from "./steps/asset-wrappers";
+import { resolveMixedArrays } from "./steps/mixed-arrays";
+import { resolveBuilders } from "./steps/builders";
+import { resolveSwitches } from "./steps/switches";
+import { resolveTemplates } from "./steps/templates";
+
+/**
+ * Creates a nested context for child assets
+ * This is Step 3 of the build process
+ */
+function createNestedParentContext<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  context: C | undefined,
+): C | undefined {
+  if (!context) {
+    return undefined;
+  }
+
+  // Extract parent ID with type checking
+  const parentId =
+    "id" in result && typeof result.id === "string" ? result.id : undefined;
+
+  // Create context for nested assets
+  // We clear the branch to avoid double-nesting
+  return {
+    ...context,
+    parentId,
+    branch: undefined,
+  } as C;
+}
+
+/**
+ * Executes the complete build pipeline
+ *
+ * The pipeline consists of 8 steps that transform builder state into a final object:
+ * 1. Resolve static values (extract TaggedTemplateValue, resolve simple builders)
+ * 2. Generate asset ID if needed
+ * 3. Create nested context for child assets
+ * 4. Resolve AssetWrapper values
+ * 5. Resolve mixed arrays
+ * 6. Resolve builders
+ * 7. Resolve switches
+ * 8. Resolve templates
+ *
+ * @param valueStorage - Storage containing property values
+ * @param auxiliaryStorage - Storage containing metadata (templates, switches)
+ * @param defaults - Optional default values to merge into result
+ * @param context - Optional build context
+ * @param arrayProperties - Set of property names that are array types
+ * @returns The fully built object
+ */
+export function executeBuildPipeline<T, C extends BaseBuildContext>(
+  valueStorage: ValueStorage<T>,
+  auxiliaryStorage: AuxiliaryStorage,
+  defaults: Partial<T> | undefined,
+  context: C | undefined,
+  arrayProperties: ReadonlySet<string>,
+): T {
+  const result: Record<string, unknown> = defaults ? { ...defaults } : {};
+
+  // Step 1: Resolve static values
+  resolveStaticValues(valueStorage, result, context);
+
+  // Step 2: Generate asset ID if needed
+  generateAssetIdForBuilder(valueStorage, result, context);
+
+  // Step 3: Create nested context for child assets
+  const nestedParentContext = createNestedParentContext(result, context);
+
+  // Step 4: Resolve AssetWrapper values
+  resolveAssetWrappers(valueStorage, result, nestedParentContext);
+
+  // Step 5: Resolve mixed arrays
+  resolveMixedArrays(valueStorage, result, nestedParentContext);
+
+  // Step 6: Resolve builders
+  resolveBuilders(valueStorage, result, nestedParentContext);
+
+  // Step 7: Resolve switches
+  resolveSwitches(
+    auxiliaryStorage,
+    result,
+    nestedParentContext,
+    arrayProperties,
+  );
+
+  // Step 8: Resolve templates
+  resolveTemplates(auxiliaryStorage, result, context);
+
+  return result as T;
+}