@dynamic-icon/core 0.1.1 → 0.1.2

package/README.md

@@ -1 +1,17 @@
 # @dynamic-icon/core
+
+> Experimental package — do not use in production.
+
+Framework-independent icon registry behind [`@dynamic-icon/svelte`](../svelte): maps `webType` + `webRef` strings from a
+database to components. Zero dependencies, no DOM, no framework. Most apps use `configureIcons` from `@dynamic-icon/svelte`
+and never import this package directly.
+
+```ts
+import { configureIcons, resolveIcon } from '@dynamic-icon/core';
+
+configureIcons<MyComponent>({ sources: { lucide: { 'car-front': CarFront } } });
+resolveIcon<MyComponent>('lucide', 'car-front'); // CarFront | undefined
+```
+
+**Full reference** (options, logging, registry, SSR rules): [`llms.txt`](./llms.txt), shipped in the npm package, e.g.
+`https://unpkg.com/@dynamic-icon/core/llms.txt`.

package/dist/config.js

@@ -1,24 +1,18 @@
 /** `webType`s handled by the renderer itself and therefore not usable as source names. */
 const RESERVED = new Set(["image", "emoji", "markup"]);
 const DEFAULT_FONT_TYPES = ["material", "font-awesome", "remix"];
+/** Distinct messages reported per configuration; protects against unbounded growth from bad data. */
+const MAX_LOGGED = 500;
+const defaultLog = ({ type, message, error }) => error === undefined ? console[type](message) : console[type](message, error);
 function positive(name, value) {
     if (!Number.isFinite(value) || value <= 0) {
         throw new RangeError(`[dynamic-icon] ${name} must be a positive finite number, got ${value}`);
     }
     return value;
 }
-function toResolver(type, source, report) {
-    if (typeof source === "function") {
-        return (ref) => {
-            try {
-                return source(ref);
-            }
-            catch (error) {
-                report(error);
-                return undefined;
-            }
-        };
-    }
+function toResolver(type, source) {
+    if (typeof source === "function")
+        return source;
     if (source !== null && typeof source === "object") {
         // Held by reference, never copied: no extra memory, and module namespaces work as-is. `hasOwn` keeps
         // identifiers such as "constructor" or "toString" from reaching Object.prototype. Treat the object as
@@ -31,16 +25,40 @@ function build(config) {
     if (config.sanitize !== undefined && typeof config.sanitize !== "function") {
         throw new TypeError("[dynamic-icon] sanitize must be a function");
     }
-    if (config.onError !== undefined && typeof config.onError !== "function") {
-        throw new TypeError("[dynamic-icon] onError must be a function");
+    if (config.onLog !== undefined && typeof config.onLog !== "function") {
+        throw new TypeError("[dynamic-icon] onLog must be a function");
     }
-    const report = config.onError ?? ((error) => console.error("[dynamic-icon]", error));
+    // Each distinct message is delivered once per configuration (so 1,000 icons with one typo log once, and a
+    // server does not log per request). A throwing `onLog` never reaches rendering.
+    const onLog = config.onLog ?? defaultLog;
+    const seen = new Set();
+    const emit = (entry) => {
+        try {
+            onLog(entry);
+        }
+        catch {
+            /* logging must never break rendering */
+        }
+    };
+    const log = (type, message, error) => {
+        if (seen.has(message))
+            return;
+        if (seen.size >= MAX_LOGGED) {
+            if (seen.size === MAX_LOGGED) {
+                seen.add(""); // marks the notice as sent
+                emit({ type: "warn", message: "[dynamic-icon] too many distinct messages; further ones are suppressed" });
+            }
+            return;
+        }
+        seen.add(message);
+        emit(error === undefined ? { type, message } : { type, message, error });
+    };
     const resolvers = new Map();
     for (const [type, source] of Object.entries(config.sources ?? {})) {
         if (RESERVED.has(type)) {
             throw new Error(`[dynamic-icon] "${type}" is a built-in type and cannot be used as a source name`);
         }
-        resolvers.set(type, toResolver(type, source, report));
+        resolvers.set(type, toResolver(type, source));
     }
     const fontTypes = new Set(config.fontTypes ?? DEFAULT_FONT_TYPES);
     for (const type of fontTypes) {
@@ -50,7 +68,31 @@ function build(config) {
     }
     const { sanitize } = config;
     return {
-        resolve: (webType, webRef) => (webType && webRef ? resolvers.get(webType)?.(webRef) : undefined),
+        resolve: (webType, webRef) => {
+            if (!webType || !webRef)
+                return undefined; // an empty record is not an error
+            const resolver = resolvers.get(webType);
+            if (resolver) {
+                try {
+                    const component = resolver(webRef);
+                    if (component === undefined)
+                        log("warn", `[dynamic-icon] icon "${webRef}" not found in source "${webType}"`);
+                    return component;
+                }
+                catch (error) {
+                    log("error", `[dynamic-icon] source "${webType}" threw while resolving "${webRef}"`, error);
+                    return undefined;
+                }
+            }
+            // Not a source: only the built-in renderers are legitimate here, anything else is a data/config bug.
+            if (!RESERVED.has(webType) && !fontTypes.has(webType)) {
+                log("warn", `[dynamic-icon] unknown webType "${webType}" (not a source, built-in or font type); icon "${webRef}" not rendered`);
+            }
+            else if (webType === "markup" && !sanitize) {
+                log("error", '[dynamic-icon] "markup" icon not rendered: configureIcons({ sanitize }) is not set');
+            }
+            return undefined;
+        },
         fontTypes,
         sanitize: sanitize
             ? (html) => {
@@ -58,7 +100,7 @@ function build(config) {
                     return sanitize(html);
                 }
                 catch (error) {
-                    report(error);
+                    log("error", "[dynamic-icon] sanitize threw; icon rendered empty", error);
                     return "";
                 }
             }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { configureIcons, getIconConfig, resolveIcon } from "./config.js";
-export type { IconConfig, IconSource, ResolvedIconConfig } from "./types.js";
+export type { IconConfig, IconLogEntry, IconSource, ResolvedIconConfig } from "./types.js";

package/dist/types.d.ts

@@ -4,6 +4,12 @@
  * - A function: full control (lazy tables, key normalisation, memoisation, ...).
  */
 export type IconSource<C = unknown> = Readonly<Record<string, C>> | ((ref: string) => C | undefined);
+export interface IconLogEntry {
+    type: "error" | "warn";
+    message: string;
+    /** The original thrown value, when there is one. */
+    error?: unknown;
+}
 export interface IconConfig<C = unknown> {
     /** Component sources by `webType`. Reserved names: `image`, `emoji`, `markup`. */
     sources?: Readonly<Record<string, IconSource<C>>>;
@@ -18,15 +24,19 @@ export interface IconConfig<C = unknown> {
         size?: number;
         strokeWidth?: number;
     };
-    /** Receives errors thrown by function sources or `sanitize`. Default: `console.error`. The icon renders as unresolved. */
-    onError?: (error: unknown) => void;
+    /**
+     * Receives diagnostics: icons missing from a source, unknown `webType`s, `markup` without `sanitize`, and
+     * errors thrown by function sources or `sanitize` (`error` carries the original). Each distinct message is
+     * delivered once. Default: `console.warn` / `console.error`. Override to silence or route (e.g. dev only).
+     */
+    onLog?: (entry: IconLogEntry) => void;
 }
 /** Validated configuration built by `configureIcons`. Record sources are referenced, not copied. */
 export interface ResolvedIconConfig<C = unknown> {
     /** Component for `webType`/`webRef`, or `undefined`. Never throws. */
     readonly resolve: (webType: string | undefined, webRef: string | undefined) => C | undefined;
     readonly fontTypes: ReadonlySet<string>;
-    /** Never throws: returns `''` if the user's sanitizer throws. */
+    /** Never throws: logs and returns `''` if the user's sanitizer throws. */
     readonly sanitize: ((html: string) => string) | undefined;
     readonly fallback: C | undefined;
     readonly size: number;

package/llms.txt

@@ -1,54 +1,55 @@
 # @dynamic-icon/core
 
-Framework-independent icon registry. It maps `webType` + `webRef` pairs stored in a database (`lucide` + `car-front`)
-to components, and holds the fallback, defaults and markup sanitizer. **Zero dependencies, no DOM, no framework**
-(compiled with `lib: ES2022` only). The component type is a generic parameter, so any UI framework can reuse it;
-[`@dynamic-icon/svelte`](../svelte) is the Svelte 5 binding and re-exports everything you need.
-
-Most apps never import this package directly; they use `configureIcons` from `@dynamic-icon/svelte`.
-
-```ts
-import { configureIcons, resolveIcon } from '@dynamic-icon/core';
-
-configureIcons<MyComponent>({
-  sources: {
-    lucide: { 'car-front': CarFront },            // record keyed by the DB identifier (held by reference)
-    svg: (ref) => customIcons[toPascal(ref)]      // or a function: full control, memoise it yourself
-  },
-  fallback: CircleHelp,
-  defaults: { size: 24, strokeWidth: 2 },
-  sanitize: (html) => DOMPurify.sanitize(html),   // required for `markup`
-  onError: (e) => report(e)                       // function sources / sanitize that throw; default console.error
-});
-
-resolveIcon<MyComponent>('lucide', 'car-front'); // CarFront | undefined
-```
-
-## Behaviour
-
-- `configureIcons` validates eagerly (reserved names `image`/`emoji`/`markup`, non-positive defaults, wrong types), **throws and
-  keeps the previous configuration** on error, and otherwise replaces the whole configuration.
-- Record sources are **held by reference, never copied** (no extra memory; module namespaces work as-is). Lookups use
-  `Object.hasOwn`, so `constructor` / `__proto__` never resolve to `Object.prototype` members. Treat source objects as read-only:
-  later mutations are visible to lookups (and, on a server, would be shared across requests).
-- Function sources and `sanitize` are wrapped: a throw is reported to `onError` and the icon renders as unresolved.
-- The registry lives on `globalThis[Symbol.for('@dynamic-icon/core@1')]` and is captured once per module, so reads are a plain
-  property access. Duplicate installs of this package share one registry. The `@1` is the holder's format version.
-- SSR: the configuration is app-wide data that never changes per request, identical for every request, so a process-wide singleton is safe.
-  Call `configureIcons` once at module scope (e.g. `hooks.server.ts` / root `+layout.ts`), never per request or per component.
-
-> Framework-independent, zero-dependency icon registry. Maps `webType` + `webRef` strings from a database to components, and stores fallback, defaults, a markup sanitizer and an error hook. The component type is a generic parameter `C`. For Svelte 5 use `@dynamic-icon/svelte`, which re-exports a typed `configureIcons` / `resolveIcon` over this package.
-
-Key facts:
-- API: `configureIcons<C>(config)`, `resolveIcon<C>(webType, webRef): C | undefined`, `getIconConfig<C>()`.
-- `configureIcons` validates eagerly, throws (keeping the previous config) on invalid input, and replaces the whole configuration.
-- Record sources are held by reference (never copied; looked up with `Object.hasOwn`, so prototype keys cannot resolve; treat them as read-only); function sources and `sanitize` never throw to the caller (errors go to `onError`, default `console.error`).
-- State lives on `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured once per module; duplicate installs share one registry.
-- Reserved `webType` names (not allowed as source names): `image`, `emoji`, `markup`.
+> Framework-independent, zero-dependency icon registry. Maps `webType` + `webRef` strings from a database to components, and stores fallback, defaults, a markup sanitizer and a log hook. The component type is a generic parameter `C`. For Svelte 5 use `@dynamic-icon/svelte`, which re-exports a typed `configureIcons` / `resolveIcon` over this package.
+
+## API
+
+- `configureIcons<C>(config: IconConfig<C>): void`: validates eagerly and replaces the whole configuration. On invalid input it throws and the previous configuration stays active.
+- `resolveIcon<C>(webType, webRef): C | undefined`: the lookup the component uses. Never throws.
+- `getIconConfig<C>(): ResolvedIconConfig<C>`: the current configuration (defaults apply until `configureIcons` is called).
+
+## IconConfig
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sources` | `Record<webType, Record<ref, C> \| (ref) => C \| undefined>` | `{}` | Component sources by `webType`. `image`, `emoji`, `markup` are reserved and throw. |
+| `fontTypes` | `string[]` | `['material','font-awesome','remix']` | `webType`s rendered as `<i class={webRef}>` by the framework binding. Must not collide with sources or reserved names. |
+| `sanitize` | `(html: string) => string` | none | Required for `markup`. Failures are logged and yield `''`. |
+| `fallback` | `C` | none | Rendered by the framework binding when nothing resolves. |
+| `defaults` | `{ size?: number; strokeWidth?: number }` | `{ size: 24, strokeWidth: 2 }` | Must be positive finite numbers or it throws. |
+| `onLog` | `(entry: { type: 'error' \| 'warn'; message: string; error?: unknown }) => void` | `console.warn` / `console.error` | Receives diagnostics (below). Override to silence or route, e.g. dev only. |
+
+## Sources
+
+- A record is held **by reference, never copied** (no extra memory; module namespaces work as-is). Lookups use `Object.hasOwn`, so `constructor`, `__proto__`, `toString` never resolve. Treat the object as read-only: later mutations are visible to lookups, and on a server would be shared across requests.
+- A function source gets full control (key normalisation, lazy tables, memoisation). It is the way to defer loading; there is no separate getter mode.
+
+## Logging (`onLog`)
+
+Reported by `resolve` (so for every icon the framework binding renders):
+
+| When | type | message |
+| --- | --- | --- |
+| `webType` is a configured source but the ref is missing | `warn` | `icon "x" not found in source "lucide"` |
+| `webType` is not a source, built-in (`image`, `emoji`, `markup`) or font type | `warn` | `unknown webType "x" ...` |
+| `webType` is `markup` and no `sanitize` is configured | `error` | `"markup" icon not rendered: configureIcons({ sanitize }) is not set` |
+| A function source throws | `error` (+ `error`) | `source "x" threw while resolving "y"` |
+| `sanitize` throws | `error` (+ `error`) | `sanitize threw; icon rendered empty` |
+
+Not logged: empty records (no `webType` or no `webRef`), built-in types, font types.
+Each distinct message is delivered **once per configuration** (1,000 icons with one typo log once; a server does not log per request). After 500 distinct messages one suppression notice is sent and the rest are dropped. A throwing `onLog` is swallowed: logging never breaks rendering.
+
+Dev-only logging in a Vite app: `onLog: import.meta.env.DEV ? undefined : () => {}` (`undefined` keeps the console default).
+
+## Registry and SSR
+
+- State is one holder object on `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured once per module so reads are plain property access. Duplicate installs share it; `@1` is the holder format version (bumped on breaking changes so incompatible copies never share state).
+- The configuration is app-wide data that does not vary per request, so a process-wide singleton is safe on the server. Call `configureIcons` once at module scope, identically on server and client; never per request or per component. Per-request or per-tenant icon sets are not supported.
+- Built with `lib: ES2022` only: no DOM, no Node typings, no dependencies.
 
 ## Docs
 
-- [Full documentation (Svelte binding + core)](https://unpkg.com/@dynamic-icon/svelte/llms-full.txt)
+- [Svelte binding and full documentation](https://unpkg.com/@dynamic-icon/svelte/llms-full.txt)
 - [README](https://unpkg.com/@dynamic-icon/core/README.md)
 
 ## Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-icon/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Framework-independent icon registry: maps database identifiers to components. Zero dependencies.",
   "license": "MIT",
   "type": "module",