assign-gingerly 0.0.84 → 0.0.85

package/parseWithAttrs.ts

@@ -1,4 +1,4 @@
-import { AttrPatterns, AttrConfig, ParserFunction, ParserContext, SpawnContext } from './types/assign-gingerly/types';
+import { AttrPatterns, AttrConfig, ParserFunction, ParserContext, SpawnContext, ParserSpec, AttrParserConstructor, NamedParserRef } from './types/assign-gingerly/types';
 import { globalParserRegistry, getParserRegistry } from './parserRegistry.js';
 import { resolveTemplate } from './resolve/resolveTemplate.js';
 
@@ -6,21 +6,79 @@ import { resolveTemplate } from './resolve/resolveTemplate.js';
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
 const parseCache = new Map<string, Map<string, any>>();
 
+/**
+ * Detects whether a value is a class-based parser constructor.
+ * Class parsers must have a `parse` method on their prototype.
+ */
+function isAttrParserConstructor(
+  value: ParserFunction | AttrParserConstructor | undefined
+): value is AttrParserConstructor {
+  return typeof value === 'function' && !!value.prototype && 'parse' in value.prototype;
+}
+
+/**
+ * Instantiates a class parser and returns a wrapper function that calls its parse method.
+ * A new instance is created for each attribute parse (no cross-call caching).
+ */
+function instantiateClassParser(
+  ParserCtor: AttrParserConstructor,
+  options?: any
+): ParserFunction {
+  const instance = new ParserCtor(options);
+  return (attrValue, context) => instance.parse(attrValue, context);
+}
+
+/**
+ * Looks up a named parser in the scoped (if available) then global registry.
+ */
+function lookupNamedParser(
+  name: string,
+  synthesizerElement?: Element
+): ParserFunction | AttrParserConstructor {
+  // Check scoped registry first (if synthesizerElement provided)
+  if (synthesizerElement) {
+    const scopedRegistry = getParserRegistry(synthesizerElement);
+    const scopedParser = scopedRegistry.get(name);
+    if (scopedParser) {
+      return scopedParser;
+    }
+  }
+  
+  // Fallback to global registry
+  const globalParser = globalParserRegistry.get(name);
+  if (globalParser) {
+    return globalParser;
+  }
+  
+  // Not found in either registry
+  throw new Error(
+    `Parser "${name}" not found. ` +
+    `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
+    `Ensure the parser is registered via:\n` +
+    `- <script type="emc-parser" src="..." parser-name="${name}">\n` +
+    `- registerParser(synthesizerElement, "${name}", parserFn)\n` +
+    `- globalParserRegistry.register("${name}", parserFn)`
+  );
+}
+
 /**
  * Resolves a parser specification to an actual parser function
  * Supports:
  * - Inline functions (direct use)
- * - Named parsers from scoped registry (if synthesizerElement provided)
- * - Named parsers from global registry (fallback)
+ * - Named parser functions or class constructors from scoped/global registry (string form)
+ * - Named class parsers with options from the object form { name, options }
+ * - Custom element static methods via tuple form [elementName, methodName]
  * 
- * @param parserSpec - Parser function or string reference
+ * @param parserSpec - Parser function, string reference, tuple, or object reference
  * @param synthesizerElement - Optional synthesizer element for scoped parser lookup
+ * @param parserOptions - Optional constructor options when a string resolves to a class parser
  * @returns The resolved parser function
  * @throws Error if parser cannot be resolved
  */
 function resolveParser(
-  parserSpec: ParserFunction | string | undefined,
-  synthesizerElement?: Element
+  parserSpec: ParserSpec | undefined,
+  synthesizerElement?: Element,
+  parserOptions?: any
 ): ParserFunction | undefined {
   // Undefined - no parser specified
   if (parserSpec === undefined) {
@@ -32,37 +90,71 @@ function resolveParser(
     return parserSpec;
   }
   
+  // Object form: { name, options }
+  if (
+    parserSpec !== null &&
+    typeof parserSpec === 'object' &&
+    !Array.isArray(parserSpec) &&
+    'name' in parserSpec
+  ) {
+    const { name, options } = parserSpec as NamedParserRef;
+    const registered = lookupNamedParser(name, synthesizerElement);
+    if (isAttrParserConstructor(registered)) {
+      return instantiateClassParser(registered, options);
+    }
+    return registered;
+  }
+  
   // String reference - resolve from scoped or global registry
   if (typeof parserSpec === 'string') {
-    // Check scoped registry first (if synthesizerElement provided)
-    if (synthesizerElement) {
-      const scopedRegistry = getParserRegistry(synthesizerElement);
-      const scopedParser = scopedRegistry.get(parserSpec);
-      if (scopedParser) {
-        return scopedParser;
-      }
+    const registered = lookupNamedParser(parserSpec, synthesizerElement);
+    if (isAttrParserConstructor(registered)) {
+      return instantiateClassParser(registered, parserOptions);
     }
-    
-    // Fallback to global registry
-    const globalParser = globalParserRegistry.get(parserSpec);
-    if (globalParser) {
-      return globalParser;
+    return registered;
+  }
+  
+  // Tuple reference: [elementName, methodName]
+  if (Array.isArray(parserSpec) && parserSpec.length === 2) {
+    const [elementName, methodName] = parserSpec;
+    const Ctr = customElements.get(elementName);
+    if (!Ctr) {
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`
+      );
     }
-    
-    // Not found in either registry
-    throw new Error(
-      `Parser "${parserSpec}" not found. ` +
-      `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
-      `Ensure the parser is registered via:\n` +
-      `- <script type="emc-parser" src="..." parser-name="${parserSpec}">\n` +
-      `- registerParser(synthesizerElement, "${parserSpec}", parserFn)\n` +
-      `- globalParserRegistry.register("${parserSpec}", parserFn)`
-    );
+    const method = (Ctr as any)[methodName];
+    if (typeof method !== 'function') {
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`
+      );
+    }
+    return method.bind(Ctr);
   }
   
   return undefined;
 }
 
+/**
+ * Serializes parser options for use in cache keys.
+ * RegExp values are normalized to their string representation.
+ */
+function serializeParserOptions(options: any): string {
+  if (options === undefined || options === null) {
+    return '';
+  }
+  try {
+    return JSON.stringify(options, (_key, value) => {
+      if (value instanceof RegExp) {
+        return value.toString();
+      }
+      return value;
+    });
+  } catch (_e) {
+    return String(options);
+  }
+}
+
 /**
  * Creates a cache key from an AttrConfig
  * Includes instanceOf and parser identifier to ensure correct cache hits
@@ -77,7 +169,19 @@ function getCacheKey(config: AttrConfig<any>): string {
   if (config.parser === undefined) {
     parserStr = 'builtin';
   } else if (typeof config.parser === 'string') {
-    parserStr = `named:${config.parser}`;
+    const optionsStr = serializeParserOptions(config.parserOptions);
+    parserStr = `named:${config.parser}|options:${optionsStr}`;
+  } else if (
+    config.parser !== null &&
+    typeof config.parser === 'object' &&
+    !Array.isArray(config.parser) &&
+    'name' in config.parser
+  ) {
+    const ref = config.parser as NamedParserRef;
+    const optionsStr = serializeParserOptions(ref.options);
+    parserStr = `named:${ref.name}|options:${optionsStr}`;
+  } else if (Array.isArray(config.parser)) {
+    parserStr = `tuple:${config.parser[0]},${config.parser[1]}`;
   } else {
     parserStr = 'custom';
   }
@@ -390,7 +494,7 @@ export function parseWithAttrs<T = any>(
             }
             // For Boolean without valIfNull, fall through to parser
             else {
-                const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+                const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
                 const parsedValue = callParser(parser, attrValue, parserContext);
                 const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
                 result[mapsTo as string] = parsedValue;
@@ -399,7 +503,7 @@ export function parseWithAttrs<T = any>(
         }
         
         // Attribute exists - parse normally
-        const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+        const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
         
         // Use cache if parseCache is specified
         const parsedValue = config.parseCache 

package/parserRegistry.js

@@ -1,3 +1,5 @@
+import { SplitParser } from './SplitParser.js';
+import { ScopedParserRegistry } from './ScopedParserRegistry.js';
 /**
  * Registry for named parsers that can be referenced by string name
  * Enables JSON serialization of configs with custom parsers
@@ -7,7 +9,7 @@ export class ParserRegistry {
     /**
      * Register a parser with a given name
      * @param name - The name to register the parser under
-     * @param parser - The parser function
+     * @param parser - The parser function or class constructor
      */
     register(name, parser) {
         if (this.parsers.has(name)) {
@@ -18,7 +20,7 @@ export class ParserRegistry {
     /**
      * Get a parser by name
      * @param name - The name of the parser
-     * @returns The parser function or undefined if not found
+     * @returns The parser function, class constructor, or undefined if not found
      */
     get(name) {
         return this.parsers.get(name);
@@ -55,7 +57,6 @@ export const globalParserRegistry = new ParserRegistry();
 // Register common built-in parsers
 globalParserRegistry.register('timestamp', (v) => v ? new Date(v).getTime() : null);
 globalParserRegistry.register('date', (v) => v ? new Date(v) : null);
-globalParserRegistry.register('csv', (v) => v ? v.split(',').map((s) => s.trim()) : []);
 globalParserRegistry.register('int', (v) => v ? parseInt(v, 10) : null);
 globalParserRegistry.register('float', (v) => v ? parseFloat(v) : null);
 globalParserRegistry.register('boolean', (v) => v !== null);
@@ -69,7 +70,7 @@ globalParserRegistry.register('json', (v) => {
         throw new Error(`Failed to parse JSON: "${v}". Error: ${e}`);
     }
 });
-import { ScopedParserRegistry } from './ScopedParserRegistry.js';
+globalParserRegistry.register('splitter', SplitParser);
 /**
  * Symbol for storing scoped parser registry on synthesizer elements
  * Using Symbol.for ensures the same symbol is used across different versions of the package

package/parserRegistry.ts

@@ -1,18 +1,20 @@
-import { ParserFunction } from './types/assign-gingerly/types';
+import { ParserFunction, AttrParserConstructor } from './types/assign-gingerly/types';
+import { SplitParser } from './SplitParser.js';
+import { ScopedParserRegistry } from './ScopedParserRegistry.js';
 
 /**
  * Registry for named parsers that can be referenced by string name
  * Enables JSON serialization of configs with custom parsers
  */
 export class ParserRegistry {
-  private parsers = new Map<string, ParserFunction>();
+  private parsers = new Map<string, ParserFunction | AttrParserConstructor>();
   
   /**
    * Register a parser with a given name
    * @param name - The name to register the parser under
-   * @param parser - The parser function
+   * @param parser - The parser function or class constructor
    */
-  register(name: string, parser: ParserFunction): void {
+  register(name: string, parser: ParserFunction | AttrParserConstructor): void {
     if (this.parsers.has(name)) {
       console.warn(`Parser "${name}" already registered, overwriting`);
     }
@@ -22,9 +24,9 @@ export class ParserRegistry {
   /**
    * Get a parser by name
    * @param name - The name of the parser
-   * @returns The parser function or undefined if not found
+   * @returns The parser function, class constructor, or undefined if not found
    */
-  get(name: string): ParserFunction | undefined {
+  get(name: string): ParserFunction | AttrParserConstructor | undefined {
     return this.parsers.get(name);
   }
   
@@ -70,10 +72,6 @@ globalParserRegistry.register('date', (v: string | null) =>
   v ? new Date(v) : null
 );
 
-globalParserRegistry.register('csv', (v: string | null) => 
-  v ? v.split(',').map((s: string) => s.trim()) : []
-);
-
 globalParserRegistry.register('int', (v: string | null) => 
   v ? parseInt(v, 10) : null
 );
@@ -95,7 +93,7 @@ globalParserRegistry.register('json', (v: string | null) => {
   }
 });
 
-import { ScopedParserRegistry } from './ScopedParserRegistry.js';
+globalParserRegistry.register('splitter', SplitParser);
 
 /**
  * Symbol for storing scoped parser registry on synthesizer elements
@@ -129,7 +127,7 @@ export function getParserRegistry(synthesizerElement: Element): ScopedParserRegi
 export function registerParser(
   synthesizerElement: Element,
   name: string,
-  parser: ParserFunction
+  parser: ParserFunction | AttrParserConstructor
 ): void {
   const registry = getParserRegistry(synthesizerElement);
   registry.register(name, parser);

package/types/assign-gingerly/types.d.ts

@@ -112,6 +112,36 @@ export interface ParserContext<T = any> {
   attrName: string;
 }
 
+/**
+ * Tuple reference for custom element static method parsers
+ * [elementName, methodName]
+ */
+export type ParserTuple = [CustomElementName, CustomElementConstructorStaticMethodName];
+
+/**
+ * Class-based parser interface
+ * Classes registered as named parsers are instantiated per attribute parse
+ * and their parse method is called with the attribute value and context
+ */
+export interface AttrParser<T = any> {
+  parse(attrValue: string | null, context?: ParserContext<T>): any;
+}
+
+/**
+ * Constructor signature for class-based parsers
+ */
+export type AttrParserConstructor<T = any> = {
+  new (options?: any): AttrParser<T>;
+};
+
+/**
+ * Object form for referencing a registered named parser with constructor options
+ */
+export interface NamedParserRef {
+  name: string;
+  options?: any;
+}
+
 /**
  * Parser function signature
  * Can accept just the attribute value (simple form) or value + context (advanced form)
@@ -120,6 +150,15 @@ export type ParserFunction<T = any> =
   | ((attrValue: string | null) => any)
   | ((attrValue: string | null, context?: ParserContext<T>) => any);
 
+/**
+ * Any valid parser specification for AttrConfig.parser
+ */
+export type ParserSpec<T = any> =
+  | ParserFunction<T>
+  | string
+  | ParserTuple
+  | NamedParserRef;
+
 export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   /**
    * Type of the property value (JSON-serializable string format)
@@ -148,7 +187,9 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * - Function: Inline parser function (not JSON serializable)
    *   - Simple form: (attrValue: string | null) => any
    *   - Advanced form: (attrValue: string | null, context: ParserContext) => any
-   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'csv')
+   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'splitter')
+   * - Tuple: [CustomElementName, StaticMethodName] - looks up a static method on a custom element constructor
+   * - Object: { name: string; options?: any } - looks up a registered class parser and instantiates it with the given options
    * 
    * Parser functions can optionally accept a second parameter (ParserContext) which provides:
    * - attrConfig: The full AttrConfig object for this attribute
@@ -156,10 +197,7 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * - element: The element being enhanced
    * - attrName: The resolved attribute name
    */
-  parser?: 
-    | ParserFunction<T>
-    | string
-  ;
+  parser?: ParserSpec<T>;
 
   /**
    * configuration information needed by a custom parser to properly