@player-lang/functional-dsl-generator 0.0.2-next.0

package/types/type-transformer.d.ts

@@ -0,0 +1,74 @@
+import type { NodeType, ObjectType, RefType } from "@xlr-lib/xlr";
+/**
+ * Interface for tracking Asset import needs and namespace mappings.
+ */
+export interface TypeTransformContext {
+    /** Set to true when Asset type needs to be imported */
+    setNeedsAssetImport(value: boolean): void;
+    /** Get the current Asset import need state */
+    getNeedsAssetImport(): boolean;
+    /** Track a referenced type for import */
+    trackReferencedType(typeName: string): void;
+    /** Track a namespace import */
+    trackNamespaceImport(namespaceName: string): void;
+    /** Get the namespace member map for type resolution */
+    getNamespaceMemberMap(): Map<string, string>;
+    /** Get the generic parameter symbols */
+    getGenericParamSymbols(): Set<string>;
+    /** Get the AssetWrapper ancestor's RefType for a type extending AssetWrapper (via registry) */
+    getAssetWrapperExtendsRef(typeName: string): RefType | undefined;
+}
+/**
+ * Transforms XLR types to TypeScript type strings.
+ */
+export declare class TypeTransformer {
+    private readonly context;
+    constructor(context: TypeTransformContext);
+    /**
+     * Determines if a type name should be tracked for import.
+     * A type should be tracked if it's not a generic parameter and not a builtin type.
+     * Note: PLAYER_BUILTINS (Asset, AssetWrapper, Binding, Expression) are filtered
+     * by isBuiltinType(), so no explicit Asset check is needed here.
+     */
+    private shouldTrackTypeForImport;
+    /**
+     * Transform an XLR type to a TypeScript type string.
+     * This is the core recursive transformation that adds TaggedTemplateValue support.
+     */
+    transformType(node: NodeType, forParameter?: boolean): string;
+    /**
+     * Transform a type for use in generic constraints and defaults.
+     * Unlike transformType(), this returns raw type names without FunctionalBuilder unions,
+     * since constraints define type bounds, not parameter types that accept builders.
+     *
+     * @param node - The type node to transform
+     * @returns The raw TypeScript type string
+     */
+    transformTypeForConstraint(node: NodeType): string;
+    /**
+     * Transform a reference type to TypeScript.
+     */
+    private transformRefType;
+    /**
+     * Transform a type that extends AssetWrapper into a combined union.
+     * Produces: InnerType | FunctionalBuilder<InnerType> | TypeName | FunctionalBuilder<TypeName> | FunctionalPartial<TypeName>
+     */
+    private transformAssetWrapperExtension;
+    /**
+     * Generate an inline object type for anonymous objects.
+     */
+    generateInlineObjectType(node: ObjectType, forParameter: boolean): string;
+    /**
+     * Check if a property name needs to be quoted in TypeScript.
+     * Property names with special characters like hyphens must be quoted.
+     */
+    private needsQuoting;
+    /**
+     * Get the full qualified name for a type if it's a namespace member.
+     * For example, "CrossfieldReference" -> "Validation.CrossfieldReference"
+     * if we've seen "Validation.CrossfieldReference" in the source.
+     * Returns the original name if no namespace mapping exists.
+     */
+    private resolveTypeName;
+}
+//# sourceMappingURL=type-transformer.d.ts.map

package/types/utils.d.ts

@@ -0,0 +1,205 @@
+import type { NodeType, ObjectType, StringType, NumberType, BooleanType, TupleType, RefType } from "@xlr-lib/xlr";
+import { isStringType, isNumberType, isBooleanType, isObjectType, isArrayType, isRefType, isOrType, isAndType, isRecordType, isNamedType } from "@xlr-lib/xlr-utils";
+export { isStringType, isNumberType, isBooleanType, isObjectType, isArrayType, isRefType, isOrType, isAndType, isRecordType, isNamedType, };
+/**
+ * Type guard for tuple type nodes
+ */
+export declare function isTupleType(node: NodeType): node is TupleType;
+/**
+ * Check if a primitive type has a const value (literal type)
+ */
+export declare function isPrimitiveConst(node: NodeType): node is (StringType | NumberType | BooleanType) & {
+    const: unknown;
+};
+/**
+ * Check if a ref type is an AssetWrapper
+ */
+export declare function isAssetWrapperRef(node: NodeType): boolean;
+/**
+ * Check if a NodeType resolves to a type that extends AssetWrapper.
+ * Handles:
+ * - RefType nodes resolved via type registry
+ * - Inline ObjectType nodes with an `extends` field
+ * - Transitive chains: e.g., ListItem → ListItemBase → AssetWrapper
+ * Uses cycle detection to prevent infinite recursion on circular type hierarchies.
+ *
+ * @param node - The node to check
+ * @param typeRegistry - Map of type names to their ObjectType definitions
+ * @param visited - Set of already-visited type names for cycle detection
+ * @returns true if the node resolves to a type extending AssetWrapper
+ */
+export declare function extendsAssetWrapper(node: NodeType, typeRegistry: TypeRegistry, visited?: Set<string>): boolean;
+/**
+ * Get the AssetWrapper ancestor's RefType for a node that extends AssetWrapper.
+ * Handles both inline ObjectTypes and RefType lookups via registry.
+ * This allows extracting the generic argument (e.g., ImageAsset from AssetWrapper<ImageAsset>).
+ *
+ * @param node - The node to inspect
+ * @param typeRegistry - Map of type names to their ObjectType definitions
+ * @param visited - Set of already-visited type names for cycle detection
+ * @returns The RefType of the AssetWrapper ancestor, or undefined if not found
+ */
+export declare function getAssetWrapperExtendsRef(node: NodeType, typeRegistry: TypeRegistry, visited?: Set<string>): RefType | undefined;
+/**
+ * Look up the AssetWrapper ancestor's RefType by type name via the registry.
+ * Convenience wrapper around getAssetWrapperExtendsRef for name-based lookups.
+ */
+export declare function getAssetWrapperExtendsRefByName(typeName: string, typeRegistry: TypeRegistry): RefType | undefined;
+/**
+ * Check if a ref type is an Expression
+ */
+export declare function isExpressionRef(node: NodeType): boolean;
+/**
+ * Check if a ref type is a Binding
+ */
+export declare function isBindingRef(node: NodeType): boolean;
+/**
+ * Sanitize a property name by removing surrounding quotes.
+ * TypeScript allows quoted property names like "mime-type" which may
+ * end up in XLR with quotes preserved.
+ *
+ * @example
+ * sanitizePropertyName("'mime-type'")  // "mime-type"
+ * sanitizePropertyName('"content-type"') // "content-type"
+ * sanitizePropertyName("normalProp")   // "normalProp"
+ */
+export declare function sanitizePropertyName(name: string): string;
+/**
+ * Convert a property name to PascalCase for method names.
+ * Handles camelCase, kebab-case, snake_case inputs, and quoted property names.
+ *
+ * @example
+ * toPascalCase("myProperty")  // "MyProperty"
+ * toPascalCase("my-property") // "MyProperty"
+ * toPascalCase("my_property") // "MyProperty"
+ * toPascalCase("'mime-type'") // "MimeType"
+ */
+export declare function toPascalCase(str: string): string;
+/**
+ * Convert a type name to a factory function name (camelCase)
+ */
+export declare function toFactoryName(typeName: string): string;
+/**
+ * Convert a type name to a builder class name
+ */
+export declare function toBuilderClassName(typeName: string): string;
+/**
+ * Check if an object type is complex enough to warrant its own builder class
+ */
+export declare function isComplexObjectType(obj: ObjectType): boolean;
+/**
+ * Get the asset type string from extends ref
+ */
+export declare function getAssetTypeFromExtends(obj: ObjectType): string | undefined;
+/**
+ * Information about a property for code generation
+ */
+export interface PropertyInfo {
+    name: string;
+    node: NodeType;
+    required: boolean;
+    isSlot: boolean;
+    isArraySlot: boolean;
+    isArray: boolean;
+}
+/**
+ * Extract property information from an ObjectType
+ */
+export declare function getPropertiesInfo(obj: ObjectType): PropertyInfo[];
+/**
+ * Check if a type contains an array type (directly or within a union/intersection)
+ * This handles cases like `Array<T> | T` where the property can be either
+ */
+export declare function containsArrayType(node: NodeType): boolean;
+/**
+ * Split a string by commas, but only at the top level (ignoring commas inside angle brackets).
+ * This is needed for parsing generic parameter lists like "T extends Foo<A, B>, U = Bar<C, D>"
+ *
+ * @example
+ * splitAtTopLevelCommas("T extends Foo, U = Bar") // ["T extends Foo", "U = Bar"]
+ * splitAtTopLevelCommas("T extends Foo<A, B>, U") // ["T extends Foo<A, B>", "U"]
+ */
+export declare function splitAtTopLevelCommas(str: string): string[];
+/**
+ * Extract generic usage string from generic params declaration
+ * Converts "T extends Foo, U = Bar" to "<T, U>"
+ * Handles nested generics like "T extends Foo<A, B>, U = Bar<C, D>" correctly
+ */
+export declare function extractGenericUsage(genericParams: string | undefined): string;
+/**
+ * Set of TypeScript built-in types that should never be imported.
+ * These are either global types or utility types provided by TypeScript.
+ */
+export declare const TYPESCRIPT_BUILTINS: Set<string>;
+/**
+ * Set of Player-specific built-in types that have special handling
+ * and should not be imported as regular types.
+ */
+export declare const PLAYER_BUILTINS: Set<string>;
+/**
+ * Check if a type name is a built-in type (TypeScript or Player-specific)
+ * that should not be imported.
+ */
+export declare function isBuiltinType(typeName: string): boolean;
+/**
+ * Extracts the base type name from a ref string, handling nested generics.
+ * @example
+ * extractBaseName("MyType") // "MyType"
+ * extractBaseName("MyType<T>") // "MyType"
+ * extractBaseName("Map<string, Array<T>>") // "Map"
+ */
+export declare function extractBaseName(ref: string): string;
+/**
+ * Checks if a type name is a namespaced type (e.g., "Validation.CrossfieldReference").
+ * Returns the namespace and member name if it is, null otherwise.
+ */
+export declare function parseNamespacedType(typeName: string): {
+    namespace: string;
+    member: string;
+} | null;
+/**
+ * Type registry for resolving named type references.
+ *
+ * This map stores XLR ObjectType definitions keyed by their type name.
+ * It's used by `findAssetWrapperPaths` to resolve references to named
+ * interface types when searching for nested AssetWrapper properties.
+ *
+ * Example usage:
+ * ```typescript
+ * const registry: TypeRegistry = new Map([
+ *   ["ContentCardHeader", headerObjectType],
+ *   ["SlotConfig", slotConfigObjectType],
+ * ]);
+ *
+ * // Now findAssetWrapperPaths can resolve ContentCardHeader references
+ * const paths = findAssetWrapperPaths(contentCardType, registry);
+ * ```
+ *
+ * Types should be registered when:
+ * - They are referenced by other types in the codebase
+ * - They contain AssetWrapper properties that need to be discovered
+ * - They are part of a nested type hierarchy
+ */
+export type TypeRegistry = Map<string, ObjectType>;
+/**
+ * Finds all paths to AssetWrapper properties within a type, including nested interfaces.
+ *
+ * This function recursively traverses the type tree to find all property paths
+ * that lead to AssetWrapper fields. It supports:
+ * - Direct AssetWrapper properties
+ * - Named interface references resolved via type registry
+ * - Arbitrary nesting depth
+ * - Cycle detection for recursive types
+ *
+ * @param node - The type node to search
+ * @param typeRegistry - Map of type names to their ObjectType definitions
+ * @returns Array of paths, where each path is an array of property names
+ *
+ * @example
+ * // For a type like:
+ * // interface ContentCard { header: ContentCardHeader }
+ * // interface ContentCardHeader { left: AssetWrapper }
+ * // Returns: [["header", "left"]]
+ */
+export declare function findAssetWrapperPaths(node: NodeType, typeRegistry: TypeRegistry): string[][];
+//# sourceMappingURL=utils.d.ts.map