@player-tools/fluent 0.12.1--canary.241.6077

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

@@ -0,0 +1,137 @@
+import type { Asset, AssetWrapper } from "@player-ui/types";
+import type { BaseBuildContext, FluentBuilder } from "./types";
+import { FLUENT_BUILDER_SYMBOL } from "./types";
+
+/**
+ * Type guard to check if a value is a FluentBuilder instance
+ * Checks for the builder symbol and build method
+ */
+export function isFluentBuilder<
+  T = unknown,
+  C extends BaseBuildContext = BaseBuildContext,
+>(value: unknown): value is FluentBuilder<T, C> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+
+  if (!(FLUENT_BUILDER_SYMBOL in value)) {
+    return false;
+  }
+
+  const obj = value as Record<symbol | string, unknown>;
+
+  return obj[FLUENT_BUILDER_SYMBOL] === true && typeof obj.build === "function";
+}
+
+/**
+ * Type guard to check if a value is an array of FluentBuilders
+ */
+export function isBuilderArray<
+  T = unknown,
+  C extends BaseBuildContext = BaseBuildContext,
+>(value: unknown): value is Array<FluentBuilder<T, C>> {
+  return Array.isArray(value) && value.every(isFluentBuilder);
+}
+
+/**
+ * Type guard to check if a value is a plain object (not a class instance)
+ * Returns true for objects created with {} or Object.create(null)
+ */
+export function isPlainObject(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (!value || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Type guard to check if a value is an Asset (has required 'type' property)
+ * Assets are the core building blocks in Player UI
+ */
+export function isAsset(value: unknown): value is Asset {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return "type" in obj && typeof obj.type === "string";
+}
+
+/**
+ * Type guard to check if a value is an AssetWrapper
+ * AssetWrapper has a single 'asset' property containing the wrapped value
+ */
+export function isAssetWrapper<T extends Asset = Asset>(
+  value: unknown,
+): value is AssetWrapper<T> {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return "asset" in obj && typeof obj.asset === "object" && obj.asset !== null;
+}
+
+/**
+ * Type guard to check if a value is an AssetWrapper containing an Asset
+ * More strict than isAssetWrapper - verifies the wrapped value is actually an Asset
+ */
+export function isAssetWrapperWithAsset<T extends Asset = Asset>(
+  value: unknown,
+): value is AssetWrapper<T> {
+  return isAssetWrapper(value) && isAsset(value.asset);
+}
+
+/**
+ * Type guard to check if a value is an AssetWrapper value object
+ * This is the internal representation: { asset: unknown }
+ * Used to detect values that need special handling during build
+ */
+export function isAssetWrapperValue(
+  value: unknown,
+): value is { asset: unknown } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "asset" in value &&
+    Object.keys(value).length === 1
+  );
+}
+
+/**
+ * Determines if a property value needs to be wrapped in AssetWrapper format
+ * Used during value storage to decide wrapping strategy
+ */
+export function needsAssetWrapper(value: unknown): boolean {
+  // Don't wrap if already an AssetWrapper
+  if (isAssetWrapper(value)) return false;
+
+  // Don't wrap if it's a FluentBuilder (will be resolved later)
+  if (isFluentBuilder(value)) return false;
+
+  // Wrap if it's an Asset
+  return isAsset(value);
+}
+
+/**
+ * Type guard to check if a value is a switch result object
+ * Switch results contain staticSwitch or dynamicSwitch arrays
+ */
+export function isSwitchResult(value: unknown): value is Record<
+  string,
+  unknown
+> & {
+  staticSwitch?: unknown[];
+  dynamicSwitch?: unknown[];
+} {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return "staticSwitch" in obj || "dynamicSwitch" in obj;
+}
+
+/**
+ * Type guard to check if a value is a string or undefined
+ * Useful for validating optional string properties
+ */
+export function isStringOrUndefined(
+  value: unknown,
+): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}

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

@@ -0,0 +1,290 @@
+import { globalIdRegistry } from "./registry";
+import {
+  BranchTypes,
+  type AssetMetadata,
+  type 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 (process.env.NODE_ENV !== "production" && !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 (process.env.NODE_ENV !== "production" && 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: BranchTypes.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: BranchTypes.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,72 @@
+export {
+  FLUENT_BUILDER_SYMBOL,
+  BranchTypes,
+  StorageKeys,
+  PropertyKeys,
+  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,
+  type FluentPartial,
+  type FluentPartialValue,
+} 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";
+
+export {
+  ErrorCodes,
+  FluentError,
+  createFluentError,
+  type ErrorCode,
+} from "./errors";