@humanspeak/svelte-markdown 0.8.12 → 0.8.14

package/dist/utils/token-cache.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Token Cache
+ *
+ * Efficient caching layer for parsed markdown tokens.
+ * Built on top of the existing MemoryCache infrastructure with
+ * specialized features for markdown parsing optimization.
+ *
+ * Key features:
+ * - Fast FNV-1a hashing for cache keys
+ * - LRU eviction (inherited from MemoryCache)
+ * - TTL support (inherited from MemoryCache)
+ * - Handles large markdown documents efficiently
+ *
+ * @module token-cache
+ */
+import type { SvelteMarkdownOptions } from '../types.js';
+import { MemoryCache } from './cache.js';
+import type { Token, TokensList } from './markdown-parser.js';
+/**
+ * Fast non-cryptographic hash function using FNV-1a algorithm.
+ * Optimized for speed over cryptographic security.
+ *
+ * FNV-1a (Fowler-Noll-Vo) provides:
+ * - Fast computation (single pass through string)
+ * - Good distribution (minimal collisions)
+ * - Small output size (base36 string)
+ *
+ * @param str - String to hash
+ * @returns Base36 hash string
+ *
+ * @example
+ * ```typescript
+ * const hash1 = hashString('# Hello World')
+ * const hash2 = hashString('# Hello World!')
+ * console.log(hash1 !== hash2) // true - different content = different hash
+ * ```
+ */
+declare function hashString(str: string): string;
+/**
+ * Specialized cache for markdown token storage.
+ * Extends MemoryCache with markdown-specific convenience methods.
+ *
+ * Inherits from MemoryCache:
+ * - Automatic LRU eviction when maxSize is reached
+ * - TTL-based expiration for time-sensitive content
+ * - Advanced deletion (deleteByPrefix, deleteByMagicString)
+ *
+ * Performance characteristics:
+ * - Cache hit: <1ms (vs 50-200ms parsing)
+ * - Memory: ~5MB for 50 cached documents (default maxSize)
+ * - Hash computation: ~0.05ms for 10KB, ~0.5ms for 100KB
+ *
+ * @class TokenCache
+ * @extends MemoryCache<Token[] | TokensList>
+ *
+ * @example
+ * ```typescript
+ * // Create cache with custom settings
+ * const cache = new TokenCache({
+ *     maxSize: 100,        // Cache up to 100 documents
+ *     ttl: 5 * 60 * 1000  // Expire after 5 minutes
+ * })
+ *
+ * // Check cache before parsing
+ * const cached = cache.getTokens(markdown, options)
+ * if (cached) {
+ *     return cached // Fast path - no parsing needed
+ * }
+ *
+ * // Parse and cache
+ * const tokens = lexer.lex(markdown)
+ * cache.setTokens(markdown, options, tokens)
+ * ```
+ */
+export declare class TokenCache extends MemoryCache<Token[] | TokensList> {
+    /**
+     * Creates a new TokenCache instance.
+     *
+     * @param options - Cache configuration
+     * @param options.maxSize - Maximum number of documents to cache (default: 50)
+     * @param options.ttl - Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(options?: {
+        maxSize?: number;
+        ttl?: number;
+    });
+    /**
+     * Retrieves cached tokens for given markdown source and options.
+     * Returns undefined if not cached or expired.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns Cached tokens or undefined
+     *
+     * @example
+     * ```typescript
+     * const tokens = cache.getTokens('# Hello', { gfm: true })
+     * if (tokens) {
+     *     console.log('Cache hit!')
+     * }
+     * ```
+     */
+    getTokens(source: string, options: SvelteMarkdownOptions): Token[] | TokensList | undefined;
+    /**
+     * Stores parsed tokens in cache for given markdown source and options.
+     * If cache is full, oldest entry is evicted (LRU).
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @param tokens - Parsed token array or token list
+     *
+     * @example
+     * ```typescript
+     * const tokens = lexer.lex(markdown)
+     * cache.setTokens(markdown, options, tokens)
+     * ```
+     */
+    setTokens(source: string, options: SvelteMarkdownOptions, tokens: Token[] | TokensList): void;
+    /**
+     * Checks if tokens are cached without retrieving them.
+     * Useful for cache statistics or conditional logic.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns True if cached and not expired
+     *
+     * @example
+     * ```typescript
+     * if (cache.hasTokens(markdown, options)) {
+     *     console.log('Cache hit - no parsing needed')
+     * }
+     * ```
+     */
+    hasTokens(source: string, options: SvelteMarkdownOptions): boolean;
+    /**
+     * Removes cached tokens for specific source and options.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns True if entry was removed, false if not found
+     *
+     * @example
+     * ```typescript
+     * cache.deleteTokens(markdown, options) // Remove specific cached entry
+     * ```
+     */
+    deleteTokens(source: string, options: SvelteMarkdownOptions): boolean;
+    /**
+     * Removes all cached tokens from the cache.
+     *
+     * @example
+     * ```typescript
+     * cache.clearAllTokens() // Clear entire cache
+     * ```
+     */
+    clearAllTokens(): void;
+}
+/**
+ * Global singleton instance for shared token caching.
+ * Use this instance across your application for maximum cache efficiency.
+ *
+ * @example
+ * ```typescript
+ * import { tokenCache } from './token-cache.js'
+ *
+ * const cached = tokenCache.getTokens(markdown, options)
+ * if (!cached) {
+ *     const tokens = lexer.lex(markdown)
+ *     tokenCache.setTokens(markdown, options, tokens)
+ * }
+ * ```
+ */
+export declare const tokenCache: TokenCache;
+/**
+ * Export hash function for testing purposes.
+ * @internal
+ */
+export { hashString };

package/dist/utils/token-cache.js

@@ -0,0 +1,238 @@
+/**
+ * Token Cache
+ *
+ * Efficient caching layer for parsed markdown tokens.
+ * Built on top of the existing MemoryCache infrastructure with
+ * specialized features for markdown parsing optimization.
+ *
+ * Key features:
+ * - Fast FNV-1a hashing for cache keys
+ * - LRU eviction (inherited from MemoryCache)
+ * - TTL support (inherited from MemoryCache)
+ * - Handles large markdown documents efficiently
+ *
+ * @module token-cache
+ */
+import { MemoryCache } from './cache.js';
+/**
+ * Fast non-cryptographic hash function using FNV-1a algorithm.
+ * Optimized for speed over cryptographic security.
+ *
+ * FNV-1a (Fowler-Noll-Vo) provides:
+ * - Fast computation (single pass through string)
+ * - Good distribution (minimal collisions)
+ * - Small output size (base36 string)
+ *
+ * @param str - String to hash
+ * @returns Base36 hash string
+ *
+ * @example
+ * ```typescript
+ * const hash1 = hashString('# Hello World')
+ * const hash2 = hashString('# Hello World!')
+ * console.log(hash1 !== hash2) // true - different content = different hash
+ * ```
+ */
+function hashString(str) {
+    let hash = 2166136261; // FNV offset basis (32-bit)
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        // FNV prime multiply using bit shifts (faster than multiplication)
+        hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+    }
+    // Convert to unsigned 32-bit integer and base36 string
+    return (hash >>> 0).toString(36);
+}
+/**
+ * Generates a cache key from markdown source and parser options.
+ * Combines hashes of both source content and options to ensure
+ * different parsing configurations are cached separately.
+ *
+ * Handles non-serializable options (extensions, tokenizer, hooks, etc.) by:
+ * - Serializing functions by name/toString for stable keys
+ * - Detecting and handling circular references
+ * - Including ALL options that affect parsing
+ *
+ * @param source - Raw markdown string
+ * @param options - Svelte markdown parser options
+ * @returns Composite cache key
+ *
+ * @example
+ * ```typescript
+ * const key1 = getCacheKey('# Test', { gfm: true })
+ * const key2 = getCacheKey('# Test', { gfm: false })
+ * console.log(key1 !== key2) // true - different options = different key
+ * ```
+ */
+function getCacheKey(source, options) {
+    const sourceHash = hashString(source);
+    // Safely serialize all options including functions and objects
+    const seen = new WeakSet();
+    const optionsHash = hashString(JSON.stringify(options, (_, value) => {
+        // Serialize functions by their name or source code
+        if (typeof value === 'function') {
+            return value.name || value.toString();
+        }
+        // Handle circular references
+        if (value && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        return value;
+    }));
+    return `${sourceHash}:${optionsHash}`;
+}
+/**
+ * Specialized cache for markdown token storage.
+ * Extends MemoryCache with markdown-specific convenience methods.
+ *
+ * Inherits from MemoryCache:
+ * - Automatic LRU eviction when maxSize is reached
+ * - TTL-based expiration for time-sensitive content
+ * - Advanced deletion (deleteByPrefix, deleteByMagicString)
+ *
+ * Performance characteristics:
+ * - Cache hit: <1ms (vs 50-200ms parsing)
+ * - Memory: ~5MB for 50 cached documents (default maxSize)
+ * - Hash computation: ~0.05ms for 10KB, ~0.5ms for 100KB
+ *
+ * @class TokenCache
+ * @extends MemoryCache<Token[] | TokensList>
+ *
+ * @example
+ * ```typescript
+ * // Create cache with custom settings
+ * const cache = new TokenCache({
+ *     maxSize: 100,        // Cache up to 100 documents
+ *     ttl: 5 * 60 * 1000  // Expire after 5 minutes
+ * })
+ *
+ * // Check cache before parsing
+ * const cached = cache.getTokens(markdown, options)
+ * if (cached) {
+ *     return cached // Fast path - no parsing needed
+ * }
+ *
+ * // Parse and cache
+ * const tokens = lexer.lex(markdown)
+ * cache.setTokens(markdown, options, tokens)
+ * ```
+ */
+export class TokenCache extends MemoryCache {
+    /**
+     * Creates a new TokenCache instance.
+     *
+     * @param options - Cache configuration
+     * @param options.maxSize - Maximum number of documents to cache (default: 50)
+     * @param options.ttl - Time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(options) {
+        super({ maxSize: 50, ttl: 5 * 60 * 1000, ...options });
+    }
+    /**
+     * Retrieves cached tokens for given markdown source and options.
+     * Returns undefined if not cached or expired.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns Cached tokens or undefined
+     *
+     * @example
+     * ```typescript
+     * const tokens = cache.getTokens('# Hello', { gfm: true })
+     * if (tokens) {
+     *     console.log('Cache hit!')
+     * }
+     * ```
+     */
+    getTokens(source, options) {
+        const key = getCacheKey(source, options);
+        return this.get(key);
+    }
+    /**
+     * Stores parsed tokens in cache for given markdown source and options.
+     * If cache is full, oldest entry is evicted (LRU).
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @param tokens - Parsed token array or token list
+     *
+     * @example
+     * ```typescript
+     * const tokens = lexer.lex(markdown)
+     * cache.setTokens(markdown, options, tokens)
+     * ```
+     */
+    setTokens(source, options, tokens) {
+        const key = getCacheKey(source, options);
+        this.set(key, tokens);
+    }
+    /**
+     * Checks if tokens are cached without retrieving them.
+     * Useful for cache statistics or conditional logic.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns True if cached and not expired
+     *
+     * @example
+     * ```typescript
+     * if (cache.hasTokens(markdown, options)) {
+     *     console.log('Cache hit - no parsing needed')
+     * }
+     * ```
+     */
+    hasTokens(source, options) {
+        const key = getCacheKey(source, options);
+        return this.has(key);
+    }
+    /**
+     * Removes cached tokens for specific source and options.
+     *
+     * @param source - Raw markdown string
+     * @param options - Svelte markdown parser options
+     * @returns True if entry was removed, false if not found
+     *
+     * @example
+     * ```typescript
+     * cache.deleteTokens(markdown, options) // Remove specific cached entry
+     * ```
+     */
+    deleteTokens(source, options) {
+        const key = getCacheKey(source, options);
+        return this.delete(key);
+    }
+    /**
+     * Removes all cached tokens from the cache.
+     *
+     * @example
+     * ```typescript
+     * cache.clearAllTokens() // Clear entire cache
+     * ```
+     */
+    clearAllTokens() {
+        this.clear();
+    }
+}
+/**
+ * Global singleton instance for shared token caching.
+ * Use this instance across your application for maximum cache efficiency.
+ *
+ * @example
+ * ```typescript
+ * import { tokenCache } from './token-cache.js'
+ *
+ * const cached = tokenCache.getTokens(markdown, options)
+ * if (!cached) {
+ *     const tokens = lexer.lex(markdown)
+ *     tokenCache.setTokens(markdown, options, tokens)
+ * }
+ * ```
+ */
+export const tokenCache = new TokenCache();
+/**
+ * Export hash function for testing purposes.
+ * @internal
+ */
+export { hashString };

package/dist/utils/token-cleanup.js

@@ -273,7 +273,12 @@ export const containsMultipleTags = (html) => {
 export const shrinkHtmlTokens = (tokens) => {
     const result = [];
     for (const token of tokens) {
-        if (token.type === 'list') {
+        if ('tokens' in token && Array.isArray(token.tokens)) {
+            const t = token;
+            t.tokens = shrinkHtmlTokens(t.tokens);
+            result.push(token);
+        }
+        else if (token.type === 'list') {
             token.items = token.items.map((item, index) => ({
                 ...item,
                 listItemIndex: index,

package/dist/utils/unsupportedHtmlRenderers.d.ts

@@ -19,7 +19,7 @@ export declare const buildUnsupportedHTML: () => HtmlRenderers;
  * Produces an HTML renderer map that allows only the specified tags.
  * All non‑listed tags are set to `UnsupportedHTML`.
  *
- * Each entry can be either a tag name (to use the library’s default component for that tag),
+ * Each entry can be either a tag name (to use the library's default component for that tag),
  * or a tuple `[tag, component]` to specify a custom component for that tag.
  *
  * @function allowHtmlOnly
@@ -35,11 +35,11 @@ export declare const buildUnsupportedHTML: () => HtmlRenderers;
  * // Allow a custom component for div while allowing the default for a
  * const html = allowHtmlOnly([['div', MyDiv], 'a'])
  */
-export declare const allowHtmlOnly: (allowed: Array<HtmlKey | [HtmlKey, Component | null]>) => HtmlRenderers;
+export declare const allowHtmlOnly: (_allowed: Array<HtmlKey | [HtmlKey, Component | null]>) => HtmlRenderers;
 /**
  * Produces an HTML renderer map that excludes only the specified tags.
  * Excluded tags are mapped to `UnsupportedHTML`, while all other tags use the
- * library’s default components. Optionally, you can override specific non‑excluded
+ * library's default components. Optionally, you can override specific non‑excluded
  * tags with custom components using `[tag, component]` tuples.
  *
  * Exclusions take precedence over overrides. If a tag is listed in `excluded`, an
@@ -59,4 +59,4 @@ export declare const allowHtmlOnly: (allowed: Array<HtmlKey | [HtmlKey, Componen
  * // Disable span; override 'a' to CustomA component
  * const html = excludeHtmlOnly(['span'], [['a', CustomA]])
  */
-export declare const excludeHtmlOnly: (excluded: HtmlKey[], overrides?: Array<[HtmlKey, Component | null]>) => HtmlRenderers;
+export declare const excludeHtmlOnly: (_excluded: HtmlKey[], _overrides?: Array<[HtmlKey, Component | null]>) => HtmlRenderers;

package/dist/utils/unsupportedHtmlRenderers.js

@@ -1,5 +1,8 @@
 import Html, { UnsupportedHTML } from '../renderers/html/index.js';
 import { htmlRendererKeysInternal } from './rendererKeys.js';
+import { createFilterUtilities } from './createFilterUtilities.js';
+// Create filter utilities using the generic factory
+const filterUtils = createFilterUtilities(htmlRendererKeysInternal, UnsupportedHTML, Html);
 /**
  * Builds a map of HTML renderers where every known HTML tag is mapped to `UnsupportedHTML`.
  * This is useful when you want to disable all built‑in HTML rendering and provide
@@ -13,18 +16,12 @@ import { htmlRendererKeysInternal } from './rendererKeys.js';
  *   html: buildUnsupportedHTML()
  * }
  */
-export const buildUnsupportedHTML = () => {
-    const result = {};
-    for (const key of htmlRendererKeysInternal) {
-        result[key] = UnsupportedHTML;
-    }
-    return result;
-};
+export const buildUnsupportedHTML = filterUtils.buildUnsupported;
 /**
  * Produces an HTML renderer map that allows only the specified tags.
  * All non‑listed tags are set to `UnsupportedHTML`.
  *
- * Each entry can be either a tag name (to use the library’s default component for that tag),
+ * Each entry can be either a tag name (to use the library's default component for that tag),
  * or a tuple `[tag, component]` to specify a custom component for that tag.
  *
  * @function allowHtmlOnly
@@ -40,27 +37,11 @@ export const buildUnsupportedHTML = () => {
  * // Allow a custom component for div while allowing the default for a
  * const html = allowHtmlOnly([['div', MyDiv], 'a'])
  */
-export const allowHtmlOnly = (allowed) => {
-    const result = buildUnsupportedHTML();
-    for (const entry of allowed) {
-        if (Array.isArray(entry)) {
-            const [tag, component] = entry;
-            // Only set if the tag exists in our Html map
-            if (tag in Html)
-                result[tag] = component;
-        }
-        else {
-            const tag = entry;
-            if (tag in Html)
-                result[tag] = Html[tag];
-        }
-    }
-    return result;
-};
+export const allowHtmlOnly = filterUtils.allowOnly;
 /**
  * Produces an HTML renderer map that excludes only the specified tags.
  * Excluded tags are mapped to `UnsupportedHTML`, while all other tags use the
- * library’s default components. Optionally, you can override specific non‑excluded
+ * library's default components. Optionally, you can override specific non‑excluded
  * tags with custom components using `[tag, component]` tuples.
  *
  * Exclusions take precedence over overrides. If a tag is listed in `excluded`, an
@@ -80,20 +61,4 @@ export const allowHtmlOnly = (allowed) => {
  * // Disable span; override 'a' to CustomA component
  * const html = excludeHtmlOnly(['span'], [['a', CustomA]])
  */
-export const excludeHtmlOnly = (excluded, overrides) => {
-    const result = { ...Html };
-    for (const tag of excluded) {
-        if (tag in Html)
-            result[tag] = UnsupportedHTML;
-    }
-    if (overrides) {
-        for (const [tag, component] of overrides) {
-            // Exclusions take precedence; do not override excluded tags
-            if (excluded.includes(tag))
-                continue;
-            if (tag in Html)
-                result[tag] = component;
-        }
-    }
-    return result;
-};
+export const excludeHtmlOnly = filterUtils.excludeOnly;

package/dist/utils/unsupportedRenderers.d.ts

@@ -5,7 +5,7 @@ import { type RendererKey } from './rendererKeys.js';
  * is set to the `Unsupported` component.
  *
  * @function buildUnsupportedRenderers
- * @returns {Partial<Renderers>} A map with all non‑HTML renderers set to `Unsupported`.
+ * @returns {Omit<Renderers, 'html'>} A map with all non‑HTML renderers set to `Unsupported`.
  * @example
  * import { buildUnsupportedRenderers } from '@humanspeak/svelte-markdown'
  * const renderers = {
@@ -13,17 +13,17 @@ import { type RendererKey } from './rendererKeys.js';
  *   html: {} // customize HTML separately
  * }
  */
-export declare const buildUnsupportedRenderers: () => Partial<Renderers>;
+export declare const buildUnsupportedRenderers: () => Omit<Renderers, "html">;
 /**
  * Produces a renderer map that allows only the specified markdown renderers (excluding `html`).
  * All non‑listed renderer keys are set to `Unsupported`.
- * Each entry can be either a renderer key (to use the library’s default component),
+ * Each entry can be either a renderer key (to use the library's default component),
  * or a tuple `[key, component]` to specify a custom component for that key.
  *
  * @function allowRenderersOnly
  * @param {Array<RendererKey | [RendererKey, RendererComponent]>} allowed
  *        Renderer keys to allow, or tuples for custom component overrides.
- * @returns {Partial<Renderers>} A renderer map with only the provided keys enabled.
+ * @returns {Omit<Renderers, 'html'>} A renderer map with only the provided keys enabled.
  * @example
  * // Allow only paragraph and link with defaults
  * const renderers = allowRenderersOnly(['paragraph', 'link'])
@@ -32,10 +32,10 @@ export declare const buildUnsupportedRenderers: () => Partial<Renderers>;
  * // Allow paragraph with a custom component
  * const renderers = allowRenderersOnly([['paragraph', MyParagraph]])
  */
-export declare const allowRenderersOnly: (allowed: Array<RendererKey | [RendererKey, RendererComponent]>) => Partial<Renderers>;
+export declare const allowRenderersOnly: (_allowed: Array<RendererKey | [RendererKey, RendererComponent]>) => Omit<Renderers, "html">;
 /**
  * Produces a renderer map that excludes only the specified markdown renderer keys (excluding `html`).
- * Excluded keys are mapped to `Unsupported`, while all other keys use the library’s default components.
+ * Excluded keys are mapped to `Unsupported`, while all other keys use the library's default components.
  * Optionally override specific non‑excluded keys with custom components via `[key, component]` tuples.
  *
  * Exclusions take precedence over overrides.
@@ -45,7 +45,7 @@ export declare const allowRenderersOnly: (allowed: Array<RendererKey | [Renderer
  *        Renderer keys to exclude (set to `Unsupported`).
  * @param {Array<[RendererKey, RendererComponent]>} [overrides]
  *        Optional tuples mapping non‑excluded keys to custom components.
- * @returns {Partial<Renderers>} A renderer map with only the provided keys excluded.
+ * @returns {Omit<Renderers, 'html'>} A renderer map with only the provided keys excluded.
  * @example
  * // Disable just paragraph and link, keep others as defaults
  * const renderers = excludeRenderersOnly(['paragraph', 'link'])
@@ -54,4 +54,4 @@ export declare const allowRenderersOnly: (allowed: Array<RendererKey | [Renderer
  * // Disable link; override paragraph to a custom component
  * const renderers = excludeRenderersOnly(['link'], [['paragraph', MyParagraph]])
  */
-export declare const excludeRenderersOnly: (excluded: RendererKey[], overrides?: Array<[RendererKey, RendererComponent]>) => Partial<Renderers>;
+export declare const excludeRenderersOnly: (_excluded: RendererKey[], _overrides?: Array<[RendererKey, RendererComponent]>) => Omit<Renderers, "html">;