@formspec/runtime 0.1.0-alpha.21 → 0.1.0-alpha.26

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/resolvers.ts"],"sourcesContent":["/**\n * `@formspec/runtime` - Runtime helpers for FormSpec\n *\n * This package provides utilities for working with FormSpec forms at runtime:\n * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields\n *\n * @example\n * ```typescript\n * import { defineResolvers } from \"@formspec/runtime\";\n * import { formspec, field } from \"@formspec/dsl\";\n *\n * // Define a form with dynamic enum fields\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * // Define resolvers for the form's data sources\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\" },\n *       { value: \"ca\", label: \"Canada\" },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * console.log(result.options); // [{ value: \"us\", ... }, { value: \"ca\", ... }]\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  defineResolvers,\n  type Resolver,\n  type ResolverMap,\n  type ResolverRegistry,\n} from \"./resolvers.js\";\n","/**\n * Resolver helpers for dynamic FormSpec data.\n *\n * Resolvers are functions that fetch options for dynamic enum fields\n * at runtime. This module provides type-safe utilities for defining\n * and using resolvers.\n */\n\nimport type {\n  DataSourceRegistry,\n  FetchOptionsResponse,\n  FormElement,\n  FormSpec,\n  DynamicEnumField,\n  Group,\n  Conditional,\n} from \"@formspec/core\";\n\n/**\n * A resolver function that fetches options for a data source.\n *\n * @typeParam Source - The data source key from DataSourceRegistry\n * @typeParam T - The data type for options (from DataSourceRegistry)\n *\n * @public\n */\nexport type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (\n  params?: Record<string, unknown>\n) => Promise<FetchOptionsResponse<T>>;\n\n/**\n * Extracts all dynamic enum source keys from a form's elements.\n */\ntype ExtractDynamicSources<E> =\n  E extends DynamicEnumField<string, infer S>\n    ? S\n    : E extends Group<infer Elements>\n      ? ExtractDynamicSourcesFromArray<Elements>\n      : E extends Conditional<string, unknown, infer Elements>\n        ? ExtractDynamicSourcesFromArray<Elements>\n        : never;\n\ntype ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest>\n  : never;\n\n/**\n * Map of resolver functions for a form's dynamic data sources.\n *\n * @public\n */\nexport type ResolverMap<Sources extends string> = {\n  [S in Sources]: S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n};\n\n/**\n * A resolver registry that provides type-safe access to resolvers.\n *\n * @public\n */\nexport interface ResolverRegistry<Sources extends string> {\n  /**\n   * Gets a resolver by data source name.\n   */\n  get<S extends Sources>(\n    source: S\n  ): S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n\n  /**\n   * Checks if a resolver exists for a data source.\n   */\n  has(source: string): boolean;\n\n  /**\n   * Gets all registered data source names.\n   */\n  sources(): Sources[];\n}\n\n/**\n * Extracts all dynamic enum field sources from form elements.\n */\nfunction extractSources(elements: readonly FormElement[]): Set<string> {\n  const sources = new Set<string>();\n\n  function visit(el: FormElement): void {\n    if (el._type === \"field\" && el._field === \"dynamic_enum\") {\n      // After checking _field, we know this is a DynamicEnumField\n      const dynamicField: DynamicEnumField<string, string> = el;\n      sources.add(dynamicField.source);\n    } else if (el._type === \"group\") {\n      (el as Group<readonly FormElement[]>).elements.forEach(visit);\n    } else if (el._type === \"conditional\") {\n      (el as Conditional<string, unknown, readonly FormElement[]>).elements.forEach(visit);\n    }\n  }\n\n  elements.forEach(visit);\n  return sources;\n}\n\n/**\n * Defines resolvers for a form's dynamic data sources.\n *\n * This function provides type-safe resolver definitions that match\n * the form's dynamic enum fields.\n *\n * @example\n * ```typescript\n * declare module \"@formspec/core\" {\n *   interface DataSourceRegistry {\n *     countries: { id: string; code: string; name: string };\n *   }\n * }\n *\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\", data: { id: \"us\", code: \"US\", name: \"United States\" } },\n *       { value: \"ca\", label: \"Canada\", data: { id: \"ca\", code: \"CA\", name: \"Canada\" } },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * ```\n *\n * @param form - The FormSpec containing dynamic enum fields\n * @param resolvers - Map of resolver functions for each data source\n * @returns A ResolverRegistry for type-safe access to resolvers\n *\n * @public\n */\nexport function defineResolvers<\n  E extends readonly FormElement[],\n  Sources extends string = ExtractDynamicSourcesFromArray<E> & string,\n>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources> {\n  const sourceSet = extractSources(form.elements);\n  const resolverMap = new Map<string, Resolver<keyof DataSourceRegistry>>(\n    Object.entries(resolvers) as [string, Resolver<keyof DataSourceRegistry>][]\n  );\n\n  // Validate that all sources have resolvers\n  for (const source of sourceSet) {\n    if (!resolverMap.has(source)) {\n      console.warn(`Missing resolver for data source: ${source}`);\n    }\n  }\n\n  return {\n    get<S extends Sources>(source: S) {\n      const resolver = resolverMap.get(source);\n      if (resolver === undefined) {\n        throw new Error(`No resolver found for data source: ${source}`);\n      }\n      return resolver as S extends keyof DataSourceRegistry\n        ? Resolver<S>\n        : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n    },\n\n    has(source: string): boolean {\n      return resolverMap.has(source);\n    },\n\n    sources(): Sources[] {\n      return Array.from(resolverMap.keys()) as Sources[];\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACyFA,SAAS,eAAe,UAA+C;AACrE,QAAM,UAAU,oBAAI,IAAY;AAEhC,WAAS,MAAM,IAAuB;AACpC,QAAI,GAAG,UAAU,WAAW,GAAG,WAAW,gBAAgB;AAExD,YAAM,eAAiD;AACvD,cAAQ,IAAI,aAAa,MAAM;AAAA,IACjC,WAAW,GAAG,UAAU,SAAS;AAC/B,MAAC,GAAqC,SAAS,QAAQ,KAAK;AAAA,IAC9D,WAAW,GAAG,UAAU,eAAe;AACrC,MAAC,GAA4D,SAAS,QAAQ,KAAK;AAAA,IACrF;AAAA,EACF;AAEA,WAAS,QAAQ,KAAK;AACtB,SAAO;AACT;AAwCO,SAAS,gBAGd,MAAmB,WAA4D;AAC/E,QAAM,YAAY,eAAe,KAAK,QAAQ;AAC9C,QAAM,cAAc,IAAI;AAAA,IACtB,OAAO,QAAQ,SAAS;AAAA,EAC1B;AAGA,aAAW,UAAU,WAAW;AAC9B,QAAI,CAAC,YAAY,IAAI,MAAM,GAAG;AAC5B,cAAQ,KAAK,qCAAqC,MAAM,EAAE;AAAA,IAC5D;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAuB,QAAW;AAChC,YAAM,WAAW,YAAY,IAAI,MAAM;AACvC,UAAI,aAAa,QAAW;AAC1B,cAAM,IAAI,MAAM,sCAAsC,MAAM,EAAE;AAAA,MAChE;AACA,aAAO;AAAA,IAGT;AAAA,IAEA,IAAI,QAAyB;AAC3B,aAAO,YAAY,IAAI,MAAM;AAAA,IAC/B;AAAA,IAEA,UAAqB;AACnB,aAAO,MAAM,KAAK,YAAY,KAAK,CAAC;AAAA,IACtC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/resolvers.ts"],"sourcesContent":["/**\n * `@formspec/runtime` - Runtime helpers for FormSpec\n *\n * This package provides utilities for working with FormSpec forms at runtime:\n * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields\n *\n * @example\n * ```typescript\n * import { defineResolvers } from \"@formspec/runtime\";\n * import { formspec, field } from \"@formspec/dsl\";\n *\n * // Define a form with dynamic enum fields\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * // Define resolvers for the form's data sources\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\" },\n *       { value: \"ca\", label: \"Canada\" },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * console.log(result.options); // [{ value: \"us\", ... }, { value: \"ca\", ... }]\n * ```\n *\n * @packageDocumentation\n */\n\nexport {\n  defineResolvers,\n  type ExtractDynamicSources,\n  type ExtractDynamicSourcesFromArray,\n  type Resolver,\n  type ResolverMap,\n  type ResolverRegistry,\n  type ResolverSourcesForForm,\n} from \"./resolvers.js\";\n","/**\n * Resolver helpers for dynamic FormSpec data.\n *\n * Resolvers are functions that fetch options for dynamic enum fields\n * at runtime. This module provides type-safe utilities for defining\n * and using resolvers.\n */\n\nimport type {\n  DataSourceRegistry,\n  FetchOptionsResponse,\n  FormElement,\n  FormSpec,\n  DynamicEnumField,\n  Group,\n  Conditional,\n} from \"@formspec/core\";\n\n/**\n * A resolver function that fetches options for a data source.\n *\n * @typeParam Source - The data source key from DataSourceRegistry\n * @typeParam T - The data type for options (from DataSourceRegistry)\n *\n * @public\n */\nexport type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (\n  params?: Record<string, unknown>\n) => Promise<FetchOptionsResponse<T>>;\n\n/**\n * Extracts dynamic data-source names referenced by a single FormSpec element.\n *\n * @public\n */\nexport type ExtractDynamicSources<E> =\n  E extends DynamicEnumField<string, infer S>\n    ? S\n    : E extends Group<infer Elements>\n      ? ExtractDynamicSourcesFromArray<Elements>\n      : E extends Conditional<string, unknown, infer Elements>\n        ? ExtractDynamicSourcesFromArray<Elements>\n        : never;\n\n/**\n * Extracts dynamic data-source names referenced anywhere in an element array.\n *\n * @public\n */\nexport type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest>\n  : never;\n\n/**\n * Derives the resolver source-key union for a FormSpec element array.\n *\n * @public\n */\nexport type ResolverSourcesForForm<E extends readonly FormElement[]> =\n  ExtractDynamicSourcesFromArray<E> & string;\n\n/**\n * Map of resolver functions for a form's dynamic data sources.\n *\n * @public\n */\nexport type ResolverMap<Sources extends string> = {\n  [S in Sources]: S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n};\n\n/**\n * A resolver registry that provides type-safe access to resolvers.\n *\n * @public\n */\nexport interface ResolverRegistry<Sources extends string> {\n  /**\n   * Gets a resolver by data source name.\n   */\n  get<S extends Sources>(\n    source: S\n  ): S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n\n  /**\n   * Checks if a resolver exists for a data source.\n   */\n  has(source: string): boolean;\n\n  /**\n   * Gets all registered data source names.\n   */\n  sources(): Sources[];\n}\n\n/**\n * Extracts all dynamic enum field sources from form elements.\n */\nfunction extractSources(elements: readonly FormElement[]): Set<string> {\n  const sources = new Set<string>();\n\n  function visit(el: FormElement): void {\n    if (el._type === \"field\" && el._field === \"dynamic_enum\") {\n      // After checking _field, we know this is a DynamicEnumField\n      const dynamicField: DynamicEnumField<string, string> = el;\n      sources.add(dynamicField.source);\n    } else if (el._type === \"group\") {\n      (el as Group<readonly FormElement[]>).elements.forEach(visit);\n    } else if (el._type === \"conditional\") {\n      (el as Conditional<string, unknown, readonly FormElement[]>).elements.forEach(visit);\n    }\n  }\n\n  elements.forEach(visit);\n  return sources;\n}\n\n/**\n * Defines resolvers for a form's dynamic data sources.\n *\n * This function provides type-safe resolver definitions that match\n * the form's dynamic enum fields.\n *\n * @example\n * ```typescript\n * declare module \"@formspec/core\" {\n *   interface DataSourceRegistry {\n *     countries: { id: string; code: string; name: string };\n *   }\n * }\n *\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\", data: { id: \"us\", code: \"US\", name: \"United States\" } },\n *       { value: \"ca\", label: \"Canada\", data: { id: \"ca\", code: \"CA\", name: \"Canada\" } },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * ```\n *\n * @param form - The FormSpec containing dynamic enum fields\n * @param resolvers - Map of resolver functions for each data source\n * @returns A ResolverRegistry for type-safe access to resolvers\n *\n * @public\n */\nexport function defineResolvers<\n  E extends readonly FormElement[],\n  Sources extends string = ResolverSourcesForForm<E>,\n>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources> {\n  const sourceSet = extractSources(form.elements);\n  const resolverMap = new Map<string, Resolver<keyof DataSourceRegistry>>(\n    Object.entries(resolvers) as [string, Resolver<keyof DataSourceRegistry>][]\n  );\n\n  // Validate that all sources have resolvers\n  for (const source of sourceSet) {\n    if (!resolverMap.has(source)) {\n      console.warn(`Missing resolver for data source: ${source}`);\n    }\n  }\n\n  return {\n    get<S extends Sources>(source: S) {\n      const resolver = resolverMap.get(source);\n      if (resolver === undefined) {\n        throw new Error(`No resolver found for data source: ${source}`);\n      }\n      return resolver as S extends keyof DataSourceRegistry\n        ? Resolver<S>\n        : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n    },\n\n    has(source: string): boolean {\n      return resolverMap.has(source);\n    },\n\n    sources(): Sources[] {\n      return Array.from(resolverMap.keys()) as Sources[];\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwGA,SAAS,eAAe,UAA+C;AACrE,QAAM,UAAU,oBAAI,IAAY;AAEhC,WAAS,MAAM,IAAuB;AACpC,QAAI,GAAG,UAAU,WAAW,GAAG,WAAW,gBAAgB;AAExD,YAAM,eAAiD;AACvD,cAAQ,IAAI,aAAa,MAAM;AAAA,IACjC,WAAW,GAAG,UAAU,SAAS;AAC/B,MAAC,GAAqC,SAAS,QAAQ,KAAK;AAAA,IAC9D,WAAW,GAAG,UAAU,eAAe;AACrC,MAAC,GAA4D,SAAS,QAAQ,KAAK;AAAA,IACrF;AAAA,EACF;AAEA,WAAS,QAAQ,KAAK;AACtB,SAAO;AACT;AAwCO,SAAS,gBAGd,MAAmB,WAA4D;AAC/E,QAAM,YAAY,eAAe,KAAK,QAAQ;AAC9C,QAAM,cAAc,IAAI;AAAA,IACtB,OAAO,QAAQ,SAAS;AAAA,EAC1B;AAGA,aAAW,UAAU,WAAW;AAC9B,QAAI,CAAC,YAAY,IAAI,MAAM,GAAG;AAC5B,cAAQ,KAAK,qCAAqC,MAAM,EAAE;AAAA,IAC5D;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAuB,QAAW;AAChC,YAAM,WAAW,YAAY,IAAI,MAAM;AACvC,UAAI,aAAa,QAAW;AAC1B,cAAM,IAAI,MAAM,sCAAsC,MAAM,EAAE;AAAA,MAChE;AACA,aAAO;AAAA,IAGT;AAAA,IAEA,IAAI,QAAyB;AAC3B,aAAO,YAAY,IAAI,MAAM;AAAA,IAC/B;AAAA,IAEA,UAAqB;AACnB,aAAO,MAAM,KAAK,YAAY,KAAK,CAAC;AAAA,IACtC;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.ts

@@ -32,5 +32,5 @@
  *
  * @packageDocumentation
  */
-export { defineResolvers, type Resolver, type ResolverMap, type ResolverRegistry, } from "./resolvers.js";
+export { defineResolvers, type ExtractDynamicSources, type ExtractDynamicSourcesFromArray, type Resolver, type ResolverMap, type ResolverRegistry, type ResolverSourcesForForm, } from "./resolvers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,gBAAgB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/resolvers.ts"],"sourcesContent":["/**\n * Resolver helpers for dynamic FormSpec data.\n *\n * Resolvers are functions that fetch options for dynamic enum fields\n * at runtime. This module provides type-safe utilities for defining\n * and using resolvers.\n */\n\nimport type {\n  DataSourceRegistry,\n  FetchOptionsResponse,\n  FormElement,\n  FormSpec,\n  DynamicEnumField,\n  Group,\n  Conditional,\n} from \"@formspec/core\";\n\n/**\n * A resolver function that fetches options for a data source.\n *\n * @typeParam Source - The data source key from DataSourceRegistry\n * @typeParam T - The data type for options (from DataSourceRegistry)\n *\n * @public\n */\nexport type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (\n  params?: Record<string, unknown>\n) => Promise<FetchOptionsResponse<T>>;\n\n/**\n * Extracts all dynamic enum source keys from a form's elements.\n */\ntype ExtractDynamicSources<E> =\n  E extends DynamicEnumField<string, infer S>\n    ? S\n    : E extends Group<infer Elements>\n      ? ExtractDynamicSourcesFromArray<Elements>\n      : E extends Conditional<string, unknown, infer Elements>\n        ? ExtractDynamicSourcesFromArray<Elements>\n        : never;\n\ntype ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest>\n  : never;\n\n/**\n * Map of resolver functions for a form's dynamic data sources.\n *\n * @public\n */\nexport type ResolverMap<Sources extends string> = {\n  [S in Sources]: S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n};\n\n/**\n * A resolver registry that provides type-safe access to resolvers.\n *\n * @public\n */\nexport interface ResolverRegistry<Sources extends string> {\n  /**\n   * Gets a resolver by data source name.\n   */\n  get<S extends Sources>(\n    source: S\n  ): S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n\n  /**\n   * Checks if a resolver exists for a data source.\n   */\n  has(source: string): boolean;\n\n  /**\n   * Gets all registered data source names.\n   */\n  sources(): Sources[];\n}\n\n/**\n * Extracts all dynamic enum field sources from form elements.\n */\nfunction extractSources(elements: readonly FormElement[]): Set<string> {\n  const sources = new Set<string>();\n\n  function visit(el: FormElement): void {\n    if (el._type === \"field\" && el._field === \"dynamic_enum\") {\n      // After checking _field, we know this is a DynamicEnumField\n      const dynamicField: DynamicEnumField<string, string> = el;\n      sources.add(dynamicField.source);\n    } else if (el._type === \"group\") {\n      (el as Group<readonly FormElement[]>).elements.forEach(visit);\n    } else if (el._type === \"conditional\") {\n      (el as Conditional<string, unknown, readonly FormElement[]>).elements.forEach(visit);\n    }\n  }\n\n  elements.forEach(visit);\n  return sources;\n}\n\n/**\n * Defines resolvers for a form's dynamic data sources.\n *\n * This function provides type-safe resolver definitions that match\n * the form's dynamic enum fields.\n *\n * @example\n * ```typescript\n * declare module \"@formspec/core\" {\n *   interface DataSourceRegistry {\n *     countries: { id: string; code: string; name: string };\n *   }\n * }\n *\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\", data: { id: \"us\", code: \"US\", name: \"United States\" } },\n *       { value: \"ca\", label: \"Canada\", data: { id: \"ca\", code: \"CA\", name: \"Canada\" } },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * ```\n *\n * @param form - The FormSpec containing dynamic enum fields\n * @param resolvers - Map of resolver functions for each data source\n * @returns A ResolverRegistry for type-safe access to resolvers\n *\n * @public\n */\nexport function defineResolvers<\n  E extends readonly FormElement[],\n  Sources extends string = ExtractDynamicSourcesFromArray<E> & string,\n>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources> {\n  const sourceSet = extractSources(form.elements);\n  const resolverMap = new Map<string, Resolver<keyof DataSourceRegistry>>(\n    Object.entries(resolvers) as [string, Resolver<keyof DataSourceRegistry>][]\n  );\n\n  // Validate that all sources have resolvers\n  for (const source of sourceSet) {\n    if (!resolverMap.has(source)) {\n      console.warn(`Missing resolver for data source: ${source}`);\n    }\n  }\n\n  return {\n    get<S extends Sources>(source: S) {\n      const resolver = resolverMap.get(source);\n      if (resolver === undefined) {\n        throw new Error(`No resolver found for data source: ${source}`);\n      }\n      return resolver as S extends keyof DataSourceRegistry\n        ? Resolver<S>\n        : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n    },\n\n    has(source: string): boolean {\n      return resolverMap.has(source);\n    },\n\n    sources(): Sources[] {\n      return Array.from(resolverMap.keys()) as Sources[];\n    },\n  };\n}\n"],"mappings":";AAyFA,SAAS,eAAe,UAA+C;AACrE,QAAM,UAAU,oBAAI,IAAY;AAEhC,WAAS,MAAM,IAAuB;AACpC,QAAI,GAAG,UAAU,WAAW,GAAG,WAAW,gBAAgB;AAExD,YAAM,eAAiD;AACvD,cAAQ,IAAI,aAAa,MAAM;AAAA,IACjC,WAAW,GAAG,UAAU,SAAS;AAC/B,MAAC,GAAqC,SAAS,QAAQ,KAAK;AAAA,IAC9D,WAAW,GAAG,UAAU,eAAe;AACrC,MAAC,GAA4D,SAAS,QAAQ,KAAK;AAAA,IACrF;AAAA,EACF;AAEA,WAAS,QAAQ,KAAK;AACtB,SAAO;AACT;AAwCO,SAAS,gBAGd,MAAmB,WAA4D;AAC/E,QAAM,YAAY,eAAe,KAAK,QAAQ;AAC9C,QAAM,cAAc,IAAI;AAAA,IACtB,OAAO,QAAQ,SAAS;AAAA,EAC1B;AAGA,aAAW,UAAU,WAAW;AAC9B,QAAI,CAAC,YAAY,IAAI,MAAM,GAAG;AAC5B,cAAQ,KAAK,qCAAqC,MAAM,EAAE;AAAA,IAC5D;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAuB,QAAW;AAChC,YAAM,WAAW,YAAY,IAAI,MAAM;AACvC,UAAI,aAAa,QAAW;AAC1B,cAAM,IAAI,MAAM,sCAAsC,MAAM,EAAE;AAAA,MAChE;AACA,aAAO;AAAA,IAGT;AAAA,IAEA,IAAI,QAAyB;AAC3B,aAAO,YAAY,IAAI,MAAM;AAAA,IAC/B;AAAA,IAEA,UAAqB;AACnB,aAAO,MAAM,KAAK,YAAY,KAAK,CAAC;AAAA,IACtC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/resolvers.ts"],"sourcesContent":["/**\n * Resolver helpers for dynamic FormSpec data.\n *\n * Resolvers are functions that fetch options for dynamic enum fields\n * at runtime. This module provides type-safe utilities for defining\n * and using resolvers.\n */\n\nimport type {\n  DataSourceRegistry,\n  FetchOptionsResponse,\n  FormElement,\n  FormSpec,\n  DynamicEnumField,\n  Group,\n  Conditional,\n} from \"@formspec/core\";\n\n/**\n * A resolver function that fetches options for a data source.\n *\n * @typeParam Source - The data source key from DataSourceRegistry\n * @typeParam T - The data type for options (from DataSourceRegistry)\n *\n * @public\n */\nexport type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (\n  params?: Record<string, unknown>\n) => Promise<FetchOptionsResponse<T>>;\n\n/**\n * Extracts dynamic data-source names referenced by a single FormSpec element.\n *\n * @public\n */\nexport type ExtractDynamicSources<E> =\n  E extends DynamicEnumField<string, infer S>\n    ? S\n    : E extends Group<infer Elements>\n      ? ExtractDynamicSourcesFromArray<Elements>\n      : E extends Conditional<string, unknown, infer Elements>\n        ? ExtractDynamicSourcesFromArray<Elements>\n        : never;\n\n/**\n * Extracts dynamic data-source names referenced anywhere in an element array.\n *\n * @public\n */\nexport type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [\n  infer First,\n  ...infer Rest,\n]\n  ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest>\n  : never;\n\n/**\n * Derives the resolver source-key union for a FormSpec element array.\n *\n * @public\n */\nexport type ResolverSourcesForForm<E extends readonly FormElement[]> =\n  ExtractDynamicSourcesFromArray<E> & string;\n\n/**\n * Map of resolver functions for a form's dynamic data sources.\n *\n * @public\n */\nexport type ResolverMap<Sources extends string> = {\n  [S in Sources]: S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n};\n\n/**\n * A resolver registry that provides type-safe access to resolvers.\n *\n * @public\n */\nexport interface ResolverRegistry<Sources extends string> {\n  /**\n   * Gets a resolver by data source name.\n   */\n  get<S extends Sources>(\n    source: S\n  ): S extends keyof DataSourceRegistry\n    ? Resolver<S>\n    : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n\n  /**\n   * Checks if a resolver exists for a data source.\n   */\n  has(source: string): boolean;\n\n  /**\n   * Gets all registered data source names.\n   */\n  sources(): Sources[];\n}\n\n/**\n * Extracts all dynamic enum field sources from form elements.\n */\nfunction extractSources(elements: readonly FormElement[]): Set<string> {\n  const sources = new Set<string>();\n\n  function visit(el: FormElement): void {\n    if (el._type === \"field\" && el._field === \"dynamic_enum\") {\n      // After checking _field, we know this is a DynamicEnumField\n      const dynamicField: DynamicEnumField<string, string> = el;\n      sources.add(dynamicField.source);\n    } else if (el._type === \"group\") {\n      (el as Group<readonly FormElement[]>).elements.forEach(visit);\n    } else if (el._type === \"conditional\") {\n      (el as Conditional<string, unknown, readonly FormElement[]>).elements.forEach(visit);\n    }\n  }\n\n  elements.forEach(visit);\n  return sources;\n}\n\n/**\n * Defines resolvers for a form's dynamic data sources.\n *\n * This function provides type-safe resolver definitions that match\n * the form's dynamic enum fields.\n *\n * @example\n * ```typescript\n * declare module \"@formspec/core\" {\n *   interface DataSourceRegistry {\n *     countries: { id: string; code: string; name: string };\n *   }\n * }\n *\n * const form = formspec(\n *   field.dynamicEnum(\"country\", \"countries\", { label: \"Country\" }),\n * );\n *\n * const resolvers = defineResolvers(form, {\n *   countries: async () => ({\n *     options: [\n *       { value: \"us\", label: \"United States\", data: { id: \"us\", code: \"US\", name: \"United States\" } },\n *       { value: \"ca\", label: \"Canada\", data: { id: \"ca\", code: \"CA\", name: \"Canada\" } },\n *     ],\n *     validity: \"valid\",\n *   }),\n * });\n *\n * // Use the resolver\n * const result = await resolvers.get(\"countries\")();\n * ```\n *\n * @param form - The FormSpec containing dynamic enum fields\n * @param resolvers - Map of resolver functions for each data source\n * @returns A ResolverRegistry for type-safe access to resolvers\n *\n * @public\n */\nexport function defineResolvers<\n  E extends readonly FormElement[],\n  Sources extends string = ResolverSourcesForForm<E>,\n>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources> {\n  const sourceSet = extractSources(form.elements);\n  const resolverMap = new Map<string, Resolver<keyof DataSourceRegistry>>(\n    Object.entries(resolvers) as [string, Resolver<keyof DataSourceRegistry>][]\n  );\n\n  // Validate that all sources have resolvers\n  for (const source of sourceSet) {\n    if (!resolverMap.has(source)) {\n      console.warn(`Missing resolver for data source: ${source}`);\n    }\n  }\n\n  return {\n    get<S extends Sources>(source: S) {\n      const resolver = resolverMap.get(source);\n      if (resolver === undefined) {\n        throw new Error(`No resolver found for data source: ${source}`);\n      }\n      return resolver as S extends keyof DataSourceRegistry\n        ? Resolver<S>\n        : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;\n    },\n\n    has(source: string): boolean {\n      return resolverMap.has(source);\n    },\n\n    sources(): Sources[] {\n      return Array.from(resolverMap.keys()) as Sources[];\n    },\n  };\n}\n"],"mappings":";AAwGA,SAAS,eAAe,UAA+C;AACrE,QAAM,UAAU,oBAAI,IAAY;AAEhC,WAAS,MAAM,IAAuB;AACpC,QAAI,GAAG,UAAU,WAAW,GAAG,WAAW,gBAAgB;AAExD,YAAM,eAAiD;AACvD,cAAQ,IAAI,aAAa,MAAM;AAAA,IACjC,WAAW,GAAG,UAAU,SAAS;AAC/B,MAAC,GAAqC,SAAS,QAAQ,KAAK;AAAA,IAC9D,WAAW,GAAG,UAAU,eAAe;AACrC,MAAC,GAA4D,SAAS,QAAQ,KAAK;AAAA,IACrF;AAAA,EACF;AAEA,WAAS,QAAQ,KAAK;AACtB,SAAO;AACT;AAwCO,SAAS,gBAGd,MAAmB,WAA4D;AAC/E,QAAM,YAAY,eAAe,KAAK,QAAQ;AAC9C,QAAM,cAAc,IAAI;AAAA,IACtB,OAAO,QAAQ,SAAS;AAAA,EAC1B;AAGA,aAAW,UAAU,WAAW;AAC9B,QAAI,CAAC,YAAY,IAAI,MAAM,GAAG;AAC5B,cAAQ,KAAK,qCAAqC,MAAM,EAAE;AAAA,IAC5D;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAuB,QAAW;AAChC,YAAM,WAAW,YAAY,IAAI,MAAM;AACvC,UAAI,aAAa,QAAW;AAC1B,cAAM,IAAI,MAAM,sCAAsC,MAAM,EAAE;AAAA,MAChE;AACA,aAAO;AAAA,IAGT;AAAA,IAEA,IAAI,QAAyB;AAC3B,aAAO,YAAY,IAAI,MAAM;AAAA,IAC/B;AAAA,IAEA,UAAqB;AACnB,aAAO,MAAM,KAAK,YAAY,KAAK,CAAC;AAAA,IACtC;AAAA,EACF;AACF;","names":[]}

package/dist/resolvers.d.ts

@@ -16,13 +16,26 @@ import type { DataSourceRegistry, FetchOptionsResponse, FormElement, FormSpec, D
  */
 export type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
 /**
- * Extracts all dynamic enum source keys from a form's elements.
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
+ */
+export type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
  */
-type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
-type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+export type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
     infer First,
     ...infer Rest
 ] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
 /**
  * Map of resolver functions for a form's dynamic data sources.
  *
@@ -88,6 +101,5 @@ export interface ResolverRegistry<Sources extends string> {
  *
  * @public
  */
-export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ExtractDynamicSourcesFromArray<E> & string>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
-export {};
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
 //# sourceMappingURL=resolvers.d.ts.map

package/dist/resolvers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,KAAK,EACL,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,MAAM,kBAAkB,EAAE,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAC9F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;GAEG;AACH,KAAK,qBAAqB,CAAC,CAAC,IAC1B,CAAC,SAAS,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,CAAC,GACD,CAAC,SAAS,KAAK,CAAC,MAAM,QAAQ,CAAC,GAC7B,8BAA8B,CAAC,QAAQ,CAAC,GACxC,CAAC,SAAS,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,GACpD,8BAA8B,CAAC,QAAQ,CAAC,GACxC,KAAK,CAAC;AAEhB,KAAK,8BAA8B,CAAC,QAAQ,IAAI,QAAQ,SAAS,SAAS;IACxE,MAAM,KAAK;IACX,GAAG,MAAM,IAAI;CACd,GACG,qBAAqB,CAAC,KAAK,CAAC,GAAG,8BAA8B,CAAC,IAAI,CAAC,GACnE,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,IAAI;KAC/C,CAAC,IAAI,OAAO,GAAG,CAAC,SAAS,MAAM,kBAAkB,GAC9C,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC;CACxE,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM;IACtD;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,OAAO,EACnB,MAAM,EAAE,CAAC,GACR,CAAC,SAAS,MAAM,kBAAkB,GACjC,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExE;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B;;OAEG;IACH,OAAO,IAAI,OAAO,EAAE,CAAC;CACtB;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,SAAS,WAAW,EAAE,EAChC,OAAO,SAAS,MAAM,GAAG,8BAA8B,CAAC,CAAC,CAAC,GAAG,MAAM,EACnE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAgC/E"}
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,KAAK,EACL,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,MAAM,kBAAkB,EAAE,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAC9F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IACjC,CAAC,SAAS,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,CAAC,GACD,CAAC,SAAS,KAAK,CAAC,MAAM,QAAQ,CAAC,GAC7B,8BAA8B,CAAC,QAAQ,CAAC,GACxC,CAAC,SAAS,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,GACpD,8BAA8B,CAAC,QAAQ,CAAC,GACxC,KAAK,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,CAAC,QAAQ,IAAI,QAAQ,SAAS,SAAS;IAC/E,MAAM,KAAK;IACX,GAAG,MAAM,IAAI;CACd,GACG,qBAAqB,CAAC,KAAK,CAAC,GAAG,8BAA8B,CAAC,IAAI,CAAC,GACnE,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,SAAS,WAAW,EAAE,IACjE,8BAA8B,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,IAAI;KAC/C,CAAC,IAAI,OAAO,GAAG,CAAC,SAAS,MAAM,kBAAkB,GAC9C,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC;CACxE,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM;IACtD;;OAEG;IACH,GAAG,CAAC,CAAC,SAAS,OAAO,EACnB,MAAM,EAAE,CAAC,GACR,CAAC,SAAS,MAAM,kBAAkB,GACjC,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAExE;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B;;OAEG;IACH,OAAO,IAAI,OAAO,EAAE,CAAC;CACtB;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,SAAS,WAAW,EAAE,EAChC,OAAO,SAAS,MAAM,GAAG,sBAAsB,CAAC,CAAC,CAAC,EAClD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAgC/E"}

package/dist/runtime-alpha.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `@formspec/runtime` - Runtime helpers for FormSpec
+ *
+ * This package provides utilities for working with FormSpec forms at runtime:
+ * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields
+ *
+ * @example
+ * ```typescript
+ * import { defineResolvers } from "@formspec/runtime";
+ * import { formspec, field } from "@formspec/dsl";
+ *
+ * // Define a form with dynamic enum fields
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * // Define resolvers for the form's data sources
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States" },
+ *       { value: "ca", label: "Canada" },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * console.log(result.options); // [{ value: "us", ... }, { value: "ca", ... }]
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { Conditional } from '@formspec/core';
+import type { DataSourceRegistry } from '@formspec/core';
+import type { DynamicEnumField } from '@formspec/core';
+import type { FetchOptionsResponse } from '@formspec/core';
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import type { Group } from '@formspec/core';
+
+/**
+ * Defines resolvers for a form's dynamic data sources.
+ *
+ * This function provides type-safe resolver definitions that match
+ * the form's dynamic enum fields.
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *   }
+ * }
+ *
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States", data: { id: "us", code: "US", name: "United States" } },
+ *       { value: "ca", label: "Canada", data: { id: "ca", code: "CA", name: "Canada" } },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * ```
+ *
+ * @param form - The FormSpec containing dynamic enum fields
+ * @param resolvers - Map of resolver functions for each data source
+ * @returns A ResolverRegistry for type-safe access to resolvers
+ *
+ * @public
+ */
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
+
+/**
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+
+/**
+ * A resolver function that fetches options for a data source.
+ *
+ * @typeParam Source - The data source key from DataSourceRegistry
+ * @typeParam T - The data type for options (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
+
+/**
+ * Map of resolver functions for a form's dynamic data sources.
+ *
+ * @public
+ */
+export declare type ResolverMap<Sources extends string> = {
+    [S in Sources]: S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+};
+
+/**
+ * A resolver registry that provides type-safe access to resolvers.
+ *
+ * @public
+ */
+export declare interface ResolverRegistry<Sources extends string> {
+    /**
+     * Gets a resolver by data source name.
+     */
+    get<S extends Sources>(source: S): S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+    /**
+     * Checks if a resolver exists for a data source.
+     */
+    has(source: string): boolean;
+    /**
+     * Gets all registered data source names.
+     */
+    sources(): Sources[];
+}
+
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export declare type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
+
+export { }

package/dist/runtime-beta.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `@formspec/runtime` - Runtime helpers for FormSpec
+ *
+ * This package provides utilities for working with FormSpec forms at runtime:
+ * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields
+ *
+ * @example
+ * ```typescript
+ * import { defineResolvers } from "@formspec/runtime";
+ * import { formspec, field } from "@formspec/dsl";
+ *
+ * // Define a form with dynamic enum fields
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * // Define resolvers for the form's data sources
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States" },
+ *       { value: "ca", label: "Canada" },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * console.log(result.options); // [{ value: "us", ... }, { value: "ca", ... }]
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { Conditional } from '@formspec/core';
+import type { DataSourceRegistry } from '@formspec/core';
+import type { DynamicEnumField } from '@formspec/core';
+import type { FetchOptionsResponse } from '@formspec/core';
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import type { Group } from '@formspec/core';
+
+/**
+ * Defines resolvers for a form's dynamic data sources.
+ *
+ * This function provides type-safe resolver definitions that match
+ * the form's dynamic enum fields.
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *   }
+ * }
+ *
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States", data: { id: "us", code: "US", name: "United States" } },
+ *       { value: "ca", label: "Canada", data: { id: "ca", code: "CA", name: "Canada" } },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * ```
+ *
+ * @param form - The FormSpec containing dynamic enum fields
+ * @param resolvers - Map of resolver functions for each data source
+ * @returns A ResolverRegistry for type-safe access to resolvers
+ *
+ * @public
+ */
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
+
+/**
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+
+/**
+ * A resolver function that fetches options for a data source.
+ *
+ * @typeParam Source - The data source key from DataSourceRegistry
+ * @typeParam T - The data type for options (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
+
+/**
+ * Map of resolver functions for a form's dynamic data sources.
+ *
+ * @public
+ */
+export declare type ResolverMap<Sources extends string> = {
+    [S in Sources]: S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+};
+
+/**
+ * A resolver registry that provides type-safe access to resolvers.
+ *
+ * @public
+ */
+export declare interface ResolverRegistry<Sources extends string> {
+    /**
+     * Gets a resolver by data source name.
+     */
+    get<S extends Sources>(source: S): S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+    /**
+     * Checks if a resolver exists for a data source.
+     */
+    has(source: string): boolean;
+    /**
+     * Gets all registered data source names.
+     */
+    sources(): Sources[];
+}
+
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export declare type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
+
+export { }

package/dist/runtime-internal.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `@formspec/runtime` - Runtime helpers for FormSpec
+ *
+ * This package provides utilities for working with FormSpec forms at runtime:
+ * - `defineResolvers()` - Type-safe resolver definitions for dynamic enum fields
+ *
+ * @example
+ * ```typescript
+ * import { defineResolvers } from "@formspec/runtime";
+ * import { formspec, field } from "@formspec/dsl";
+ *
+ * // Define a form with dynamic enum fields
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * // Define resolvers for the form's data sources
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States" },
+ *       { value: "ca", label: "Canada" },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * console.log(result.options); // [{ value: "us", ... }, { value: "ca", ... }]
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { Conditional } from '@formspec/core';
+import type { DataSourceRegistry } from '@formspec/core';
+import type { DynamicEnumField } from '@formspec/core';
+import type { FetchOptionsResponse } from '@formspec/core';
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import type { Group } from '@formspec/core';
+
+/**
+ * Defines resolvers for a form's dynamic data sources.
+ *
+ * This function provides type-safe resolver definitions that match
+ * the form's dynamic enum fields.
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *   }
+ * }
+ *
+ * const form = formspec(
+ *   field.dynamicEnum("country", "countries", { label: "Country" }),
+ * );
+ *
+ * const resolvers = defineResolvers(form, {
+ *   countries: async () => ({
+ *     options: [
+ *       { value: "us", label: "United States", data: { id: "us", code: "US", name: "United States" } },
+ *       { value: "ca", label: "Canada", data: { id: "ca", code: "CA", name: "Canada" } },
+ *     ],
+ *     validity: "valid",
+ *   }),
+ * });
+ *
+ * // Use the resolver
+ * const result = await resolvers.get("countries")();
+ * ```
+ *
+ * @param form - The FormSpec containing dynamic enum fields
+ * @param resolvers - Map of resolver functions for each data source
+ * @returns A ResolverRegistry for type-safe access to resolvers
+ *
+ * @public
+ */
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
+
+/**
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+
+/**
+ * A resolver function that fetches options for a data source.
+ *
+ * @typeParam Source - The data source key from DataSourceRegistry
+ * @typeParam T - The data type for options (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
+
+/**
+ * Map of resolver functions for a form's dynamic data sources.
+ *
+ * @public
+ */
+export declare type ResolverMap<Sources extends string> = {
+    [S in Sources]: S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+};
+
+/**
+ * A resolver registry that provides type-safe access to resolvers.
+ *
+ * @public
+ */
+export declare interface ResolverRegistry<Sources extends string> {
+    /**
+     * Gets a resolver by data source name.
+     */
+    get<S extends Sources>(source: S): S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+    /**
+     * Checks if a resolver exists for a data source.
+     */
+    has(source: string): boolean;
+    /**
+     * Gets all registered data source names.
+     */
+    sources(): Sources[];
+}
+
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export declare type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
+
+export { }

package/dist/runtime.d.ts

@@ -79,14 +79,21 @@ import type { Group } from '@formspec/core';
  *
  * @public
  */
-export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ExtractDynamicSourcesFromArray<E> & string>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
 
 /**
- * Extracts all dynamic enum source keys from a form's elements.
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
  */
-declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+export declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
 
-declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
 infer First,
 ...infer Rest
 ] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
@@ -130,4 +137,11 @@ export declare interface ResolverRegistry<Sources extends string> {
     sources(): Sources[];
 }
 
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export declare type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/runtime",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.26",
   "description": "Runtime helpers for FormSpec - resolvers and data fetching",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,11 +18,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@formspec/core": "0.1.0-alpha.21"
+    "@formspec/core": "0.1.0-alpha.26"
   },
   "devDependencies": {
     "vitest": "^3.0.0",
-    "@formspec/dsl": "0.1.0-alpha.21"
+    "@formspec/dsl": "0.1.0-alpha.26"
   },
   "publishConfig": {
     "access": "public"
@@ -30,12 +30,12 @@
   "keywords": [],
   "license": "UNLICENSED",
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly && api-extractor run --local",
+    "build": "tsup && tsc --emitDeclarationOnly && pnpm run api-extractor:local",
     "clean": "rm -rf dist temp",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "api-extractor": "api-extractor run",
-    "api-extractor:local": "api-extractor run --local",
-    "api-documenter": "api-documenter markdown -i temp -o docs"
+    "api-extractor": "api-extractor run && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-extractor:local": "api-extractor run --local && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-documenter": "api-documenter markdown -i temp -o docs && node ../../scripts/normalize-generated-markdown.mjs docs"
   }
 }