assign-gingerly 0.0.72 → 0.0.74

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

@@ -1,3 +1,5 @@
+import {ParserOptions} from '../nested-regex-groups/types.js';
+
 export type EnhKey = string | symbol;
 
 // type NoUnderscore<T extends string> = T extends `_${string}` ? never : T;
@@ -196,7 +198,7 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * For named parsers like 'parse-pattern-statements', this is forwarded
    * as the options argument to the underlying parse function.
    */
-  parserOptions?: any;
+  parserOptions?: ParserOptions;
 }
 
 export type AttrPatterns<T = any> = {
@@ -589,21 +591,6 @@ export interface SupportedFeatureConfig {
     callbackForwarding?: string[];
 }
 
-/**
- * Class-level configuration for the features system.
- * Declared as `static featuresConfig` on the class.
- */
-export interface FeaturesClassConfig {
-    /**
-     * Lifecycle method configuration.
-     * true = install 'whenFeatureReady' method.
-     * Object = custom method name.
-     */
-    lifecycleKeys?: true | {
-        whenFeatureReady?: string;
-    };
-}
-
 /**
  * Configuration for a feature passed to assignFeatures.
  */
@@ -613,7 +600,8 @@ export interface FeatureConfig {
      */
     spawn?:
         | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
-        | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
+        | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>)
+        | string // import path or builtIns.* alias
 
     /** Attribute patterns for parsing element attributes into initVals. */
     withAttrs?: AttrPatterns<any>;
@@ -706,8 +694,8 @@ export interface HandlerConfig {
  * Interface for assignFrom handler classes.
  * Handlers are invoked when a LHS key ends with ' =>'.
  */
-export interface AssignFromHandler {
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any, permissions?: AssignPermissions): Promise<void> | void;
+export interface AssignFromHandler {
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any, permissions?: AssignPermissions): Promise<void> | void;
 }
 
 /**
@@ -885,7 +873,7 @@ export interface LazyLoadInstantiatedContext {
 export declare class LazyLoadHandler implements AssignFromHandler {
     config: any;
     constructor(config: any);
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissions?: AssignPermissions): Promise<void>;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissions?: AssignPermissions): Promise<void>;
     protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
 }
 
@@ -969,12 +957,12 @@ export interface AssignPermissions {
     /**
      * Restricted property settings.
      * Phase I: string entries are property names that cannot be assigned.
-     * Phase II: an object with useMethod redirects ordinary assignment to that
-     * method; command operations remain blocked. Phase III+ adds attr support.
+     * Phase II: an object with useMethod redirects ordinary assignment to that
+     * method; command operations remain blocked. Phase III+ adds attr support.
      *
-     * NOTE: This is a property-assignment guard only. Method calls (setAttribute, etc.)
-     * are not blocked — see Phase III+. Event listeners can still be registered, but
-     * assignments performed by their vectors inherit these permissions.
+     * NOTE: This is a property-assignment guard only. Method calls (setAttribute, etc.)
+     * are not blocked — see Phase III+. Event listeners can still be registered, but
+     * assignments performed by their vectors inherit these permissions.
      */
     restrictedPropSettings?: Array<string | RestrictedPropSetting>;
 

package/isAllowedImportPath.js

@@ -1,104 +0,0 @@
-/**
- * isAllowedImportPath.ts — Security utility for validating import paths.
- *
- * Checks that a path is local (relative, absolute, or bare specifier) and
- * not a cross-domain URL. Used to prevent untrusted HTML attributes from
- * triggering imports to arbitrary external domains.
- *
- * @example
- * import { isAllowedImportPath } from 'assign-gingerly/isAllowedImportPath.js';
- *
- * isAllowedImportPath('./local.js');           // true
- * isAllowedImportPath('../parent/file.js');    // true
- * isAllowedImportPath('/absolute/path.js');    // true
- * isAllowedImportPath('bare-specifier/mod.js'); // true
- * isAllowedImportPath('https://evil.com/x.js'); // false
- * isAllowedImportPath('//cdn.example.com/x.js'); // false
- */
-/**
- * Module-level warn dedup — one warning per property key per process lifetime.
- */
-const warnedOnce = new Set();
-/**
- * Warn once per key that a restricted property assignment was skipped.
- */
-function warnRestricted(key) {
-    if (!warnedOnce.has(key)) {
-        warnedOnce.add(key);
-        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
-    }
-}
-/**
- * Normalize the restrictedPropSettings from permissions into a fast-lookup Set.
- * Phase I: extracts string entries only (object entries are Phase II+).
- * Returns undefined when nothing is restricted (fast-bail in callers).
- */
-export function buildRestrictedPropSet(permissions) {
-    const settings = permissions?.restrictedPropSettings;
-    if (!settings || settings.length === 0)
-        return undefined;
-    const restrictedPropSet = new Map();
-    for (const setting of settings) {
-        const prop = typeof setting === 'string' ? setting : setting.prop;
-        if (restrictedPropSet.has(prop)) {
-            throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
-        }
-        restrictedPropSet.set(prop, typeof setting === 'string' ? undefined : setting);
-    }
-    return restrictedPropSet;
-}
-/**
- * Check if a property key is restricted. If so, warn (once) and return true.
- * Call sites should `continue` or skip the assignment when this returns true.
- */
-export function checkRestrictedProp(restrictedPropSet, key) {
-    if (!restrictedPropSet || !restrictedPropSet.has(key))
-        return false;
-    warnRestricted(key);
-    return true;
-}
-/**
- * Redirect an ordinary assignment through its configured safe method.
- * Returns true when the property is restricted, whether redirected or skipped.
- */
-export function redirectRestrictedProp(restrictedPropSet, target, key, value) {
-    if (!restrictedPropSet || !restrictedPropSet.has(key))
-        return false;
-    const setting = restrictedPropSet.get(key);
-    if (!setting?.useMethod) {
-        warnRestricted(key);
-        return true;
-    }
-    const method = target?.[setting.useMethod];
-    if (typeof method !== 'function') {
-        warnRestricted(key);
-        return true;
-    }
-    method.call(target, value);
-    return true;
-}
-/**
- * Check if an import path is allowed (non-cross-domain).
- *
- * Allowed:
- * - Relative paths: ./foo.js, ../bar.js
- * - Absolute paths: /path/to/file.js
- * - Bare specifiers: package-name/file.js, @scope/package/file.js
- *
- * Blocked:
- * - Protocol URLs: https://..., http://..., data:..., etc.
- * - Protocol-relative: //cdn.example.com/...
- *
- * @param path - The import path to validate
- * @returns true if the path is local/safe, false if cross-domain
- */
-export function isAllowedImportPath(path) {
-    if (path.startsWith('./') || path.startsWith('../') || path.startsWith('/')) {
-        return true;
-    }
-    if (path.includes('://') || path.startsWith('//')) {
-        return false;
-    }
-    // Bare specifier (no protocol, no //) — allowed
-    return true;
-}

package/isAllowedImportPath.ts

@@ -1,118 +0,0 @@
-/**
- * isAllowedImportPath.ts — Security utility for validating import paths.
- * 
- * Checks that a path is local (relative, absolute, or bare specifier) and
- * not a cross-domain URL. Used to prevent untrusted HTML attributes from
- * triggering imports to arbitrary external domains.
- * 
- * @example
- * import { isAllowedImportPath } from 'assign-gingerly/isAllowedImportPath.js';
- * 
- * isAllowedImportPath('./local.js');           // true
- * isAllowedImportPath('../parent/file.js');    // true
- * isAllowedImportPath('/absolute/path.js');    // true
- * isAllowedImportPath('bare-specifier/mod.js'); // true
- * isAllowedImportPath('https://evil.com/x.js'); // false
- * isAllowedImportPath('//cdn.example.com/x.js'); // false
- */
-
-// Re-export AssignPermissions from canonical location for backwards compatibility
-export type { AssignPermissions } from './types/assign-gingerly/types.js';
-import type { AssignPermissions, RestrictedPropSetting } from './types/assign-gingerly/types.js';
-
-export type RestrictedPropSettingsMap = Map<string, RestrictedPropSetting | undefined>;
-
-/**
- * Module-level warn dedup — one warning per property key per process lifetime.
- */
-const warnedOnce = new Set<string>();
-
-/**
- * Warn once per key that a restricted property assignment was skipped.
- */
-function warnRestricted(key: string): void {
-    if (!warnedOnce.has(key)) {
-        warnedOnce.add(key);
-        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
-    }
-}
-
-/**
- * Normalize the restrictedPropSettings from permissions into a fast-lookup Set.
- * Phase I: extracts string entries only (object entries are Phase II+).
- * Returns undefined when nothing is restricted (fast-bail in callers).
- */
-export function buildRestrictedPropSet(permissions: AssignPermissions | undefined): RestrictedPropSettingsMap | undefined {
-    const settings = permissions?.restrictedPropSettings;
-    if (!settings || settings.length === 0) return undefined;
-    const restrictedPropSet: RestrictedPropSettingsMap = new Map();
-    for (const setting of settings) {
-        const prop = typeof setting === 'string' ? setting : setting.prop;
-        if (restrictedPropSet.has(prop)) {
-            throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
-        }
-        restrictedPropSet.set(prop, typeof setting === 'string' ? undefined : setting);
-    }
-    return restrictedPropSet;
-}
-
-/**
- * Check if a property key is restricted. If so, warn (once) and return true.
- * Call sites should `continue` or skip the assignment when this returns true.
- */
-export function checkRestrictedProp(restrictedPropSet: RestrictedPropSettingsMap | undefined, key: string): boolean {
-    if (!restrictedPropSet || !restrictedPropSet.has(key)) return false;
-    warnRestricted(key);
-    return true;
-}
-
-/**
- * Redirect an ordinary assignment through its configured safe method.
- * Returns true when the property is restricted, whether redirected or skipped.
- */
-export function redirectRestrictedProp(
-    restrictedPropSet: RestrictedPropSettingsMap | undefined,
-    target: any,
-    key: string,
-    value: any
-): boolean {
-    if (!restrictedPropSet || !restrictedPropSet.has(key)) return false;
-    const setting = restrictedPropSet.get(key);
-    if (!setting?.useMethod) {
-        warnRestricted(key);
-        return true;
-    }
-    const method = target?.[setting.useMethod];
-    if (typeof method !== 'function') {
-        warnRestricted(key);
-        return true;
-    }
-    method.call(target, value);
-    return true;
-}
-
-/**
- * Check if an import path is allowed (non-cross-domain).
- * 
- * Allowed:
- * - Relative paths: ./foo.js, ../bar.js
- * - Absolute paths: /path/to/file.js
- * - Bare specifiers: package-name/file.js, @scope/package/file.js
- * 
- * Blocked:
- * - Protocol URLs: https://..., http://..., data:..., etc.
- * - Protocol-relative: //cdn.example.com/...
- * 
- * @param path - The import path to validate
- * @returns true if the path is local/safe, false if cross-domain
- */
-export function isAllowedImportPath(path: string): boolean {
-    if (path.startsWith('./') || path.startsWith('../') || path.startsWith('/')) {
-        return true;
-    }
-    if (path.includes('://') || path.startsWith('//')) {
-        return false;
-    }
-    // Bare specifier (no protocol, no //) — allowed
-    return true;
-}