@asciidoctor/core 4.0.0-alpha.2 → 4.0.0-alpha.4

package/src/extensions.js

@@ -27,6 +27,94 @@ import { basename } from './helpers.js'
 import { ATTR_REF_HEAD } from './constants.js'
 import { MacroNameRx, CC_ANY } from './rx.js'
 
+// Type-only imports for JSDoc
+/**
+ * @typedef {import('./document.js').Document} Document
+ * @typedef {import('./abstract_block.js').AbstractBlock} AbstractBlock
+ */
+
+// ── DSL interface types ───────────────────────────────────────────────────────
+
+/**
+ * DSL interface for configuring a {@link Processor} instance.
+ * Applied to a processor instance via `Object.assign(instance, DslMixin)`.
+ *
+ * The `process` property behaves as a setter when called with a single Function
+ * argument (stores the process block), or as a passthrough caller otherwise.
+ *
+ * @typedef {object} ProcessorDslInterface
+ * @property {(key: string, value: unknown) => void} option - Set a config option.
+ * @property {(fn: (...args: unknown[]) => unknown) => void} process - Register the process function.
+ * @property {() => boolean} processBlockGiven - Returns true if a process function has been registered.
+ */
+
+/**
+ * DSL interface for document processors (Preprocessor, TreeProcessor, Postprocessor, DocinfoProcessor).
+ *
+ * @typedef {ProcessorDslInterface & { prefer(): void; prepend(): void }} DocumentProcessorDslInterface
+ */
+
+/**
+ * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
+ *
+ * @typedef {ProcessorDslInterface & {
+ *   named(value: string): void;
+ *   contentModel(value: string): void;
+ *   parseContentAs(value: string): void;
+ *   positionalAttributes(...value: string[]): void;
+ *   namePositionalAttributes(...value: string[]): void;
+ *   positionalAttrs(...value: string[]): void;
+ *   defaultAttributes(value: Record<string, string>): void;
+ *   defaultAttrs(value: Record<string, string>): void;
+ *   resolveAttributes(...args: unknown[]): void;
+ *   resolvesAttributes(...args: unknown[]): void;
+ * }} SyntaxProcessorDslInterface
+ */
+
+/**
+ * DSL interface for include processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (doc: Document, target: string) => boolean): void;
+ * }} IncludeProcessorDslInterface
+ */
+
+/**
+ * DSL interface for docinfo processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   atLocation(value: string): void;
+ * }} DocinfoProcessorDslInterface
+ */
+
+/**
+ * DSL interface for block processors.
+ *
+ * @typedef {SyntaxProcessorDslInterface & {
+ *   contexts(...value: (string | string[])[]): void;
+ *   onContexts(...value: (string | string[])[]): void;
+ *   onContext(...value: (string | string[])[]): void;
+ *   bindTo(...value: (string | string[])[]): void;
+ * }} BlockProcessorDslInterface
+ */
+
+/**
+ * DSL interface for macro processors (block and inline macros).
+ *
+ * @typedef {SyntaxProcessorDslInterface} MacroProcessorDslInterface
+ */
+
+/**
+ * DSL interface for inline macro processors.
+ *
+ * @typedef {MacroProcessorDslInterface & {
+ *   format(value: string): void;
+ *   matchFormat(value: string): void;
+ *   usingFormat(value: string): void;
+ *   match(value: RegExp): void;
+ * }} InlineMacroProcessorDslInterface
+ */
+
 // ── DSL Mixins ────────────────────────────────────────────────────────────────
 
 /**
@@ -625,7 +713,12 @@ export class Processor {
  * Extensions.register(function () { this.preprocessor(CommentStripPreprocessor) })
  */
 export class Preprocessor extends Processor {
-  process(_document, _reader) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader positioned at the beginning of the source.
+   * @returns {Reader|undefined} The same or a substitute Reader, or undefined to use the original.
+   */
+  process(document, reader) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -650,7 +743,11 @@ Preprocessor.DSL = DocumentProcessorDsl
  * Extensions.register(function () { this.treeProcessor(ShoutTreeProcessor) })
  */
 export class TreeProcessor extends Processor {
-  process(_document) {
+  /**
+   * @param {Document} document - The parsed document.
+   * @returns {void}
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -679,7 +776,12 @@ export const Treeprocessor = TreeProcessor
  * Extensions.register(function () { this.postprocessor(FooterPostprocessor) })
  */
 export class Postprocessor extends Processor {
-  process(_document, _output) {
+  /**
+   * @param {Document} document - The converted document.
+   * @param {string} output - The converted output string.
+   * @returns {string} The (possibly modified) output string.
+   */
+  process(document, output) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -693,13 +795,25 @@ Postprocessor.DSL = DocumentProcessorDsl
  * Implementations must extend IncludeProcessor.
  */
 export class IncludeProcessor extends Processor {
-  process(_document, _reader, _target, _attributes) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader for the including document.
+   * @param {string} target - The target of the include directive.
+   * @param {Record<string, string>} attributes - The parsed include attributes.
+   * @returns {void}
+   */
+  process(document, reader, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
   }
 
-  handles(_doc, _target) {
+  /**
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The target of the include directive.
+   * @returns {boolean} true if this processor handles the given target.
+   */
+  handles(doc, target) {
     return true
   }
 }
@@ -717,7 +831,11 @@ export class DocinfoProcessor extends Processor {
     this.config.location ??= 'head'
   }
 
-  process(_document) {
+  /**
+   * @param {Document} document - The document being converted.
+   * @returns {string} The docinfo content to inject into the document.
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -773,7 +891,13 @@ export class BlockProcessor extends Processor {
     this.config.content_model ??= 'compound'
   }
 
-  process(_parent, _reader, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {Reader} reader - The reader positioned at the block content.
+   * @param {Record<string, unknown>} attributes - The parsed block attributes.
+   * @returns {Block|void} A block node, or void to let the parser handle it.
+   */
+  process(parent, reader, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -791,7 +915,13 @@ export class MacroProcessor extends Processor {
     this.config.content_model ??= 'attributes'
   }
 
-  process(_parent, _target, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target (text between `name:` and `[`).
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block|Inline|void}
+   */
+  process(parent, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -837,6 +967,16 @@ export class BlockMacroProcessor extends MacroProcessor {
   set name(value) {
     this._name = value
   }
+
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block} A block node created with one of the `createBlock` helpers.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
 }
 BlockMacroProcessor.DSL = MacroProcessorDsl
 
@@ -880,6 +1020,16 @@ export class InlineMacroProcessor extends MacroProcessor {
     ))
   }
 
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Inline} An Inline node created with `this.createInline(...)`.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
+
   resolveRegexp(name, format) {
     if (!MacroNameRx.test(name)) {
       throw new Error(`invalid name for inline macro: ${name}`)
@@ -1263,6 +1413,15 @@ export class Registry {
     return !!this._block_extensions
   }
 
+  /**
+   * Retrieve all BlockProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blocks() {
+    return this._block_extensions ? Object.values(this._block_extensions) : []
+  }
+
   /**
    * Check whether a BlockProcessor is registered for the given name and context.
    *
@@ -1309,6 +1468,17 @@ export class Registry {
     return !!this._block_macro_extensions
   }
 
+  /**
+   * Retrieve all BlockMacroProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blockMacros() {
+    return this._block_macro_extensions
+      ? Object.values(this._block_macro_extensions)
+      : []
+  }
+
   /**
    * Check whether a BlockMacroProcessor is registered for the given name.
    *
@@ -1414,6 +1584,85 @@ export class Registry {
     return extension
   }
 
+  // ── JavaScript-style accessors ───────────────────────────────────────────────
+
+  /** @returns {object} the plain Object that maps names to groups for this registry. */
+  getGroups() {
+    return this.groups
+  }
+
+  /** Alias for {@link preprocessors}. */
+  getPreprocessors() {
+    return this.preprocessors()
+  }
+
+  /** Alias for {@link treeProcessors}. */
+  getTreeProcessors() {
+    return this.treeProcessors()
+  }
+
+  /** Alias for {@link includeProcessors}. */
+  getIncludeProcessors() {
+    return this.includeProcessors()
+  }
+
+  /** Alias for {@link postprocessors}. */
+  getPostprocessors() {
+    return this.postprocessors()
+  }
+
+  /**
+   * Alias for {@link docinfoProcessors}.
+   *
+   * @param {string|null} [location=null]
+   */
+  getDocinfoProcessors(location = null) {
+    return this.docinfoProcessors(location)
+  }
+
+  /** Alias for {@link blocks}. */
+  getBlocks() {
+    return this.blocks()
+  }
+
+  /** Alias for {@link blockMacros}. */
+  getBlockMacros() {
+    return this.blockMacros()
+  }
+
+  /** Alias for {@link inlineMacros}. */
+  getInlineMacros() {
+    return this.inlineMacros()
+  }
+
+  /**
+   * Alias for {@link registeredForInlineMacro}.
+   *
+   * @param {string} name
+   */
+  getInlineMacroFor(name) {
+    return this.registeredForInlineMacro(name)
+  }
+
+  /**
+   * Alias for {@link registeredForBlock}.
+   *
+   * @param {string} name
+   * @param {string} context
+   */
+  getBlockFor(name, context) {
+    return this.registeredForBlock(name, context)
+  }
+
+  /**
+   * Alias for {@link registeredForBlockMacro}.
+   *
+   * @param {string} name
+   */
+  getBlockMacroFor(name) {
+    return this.registeredForBlockMacro(name)
+  }
+
   // ── Private helpers ──────────────────────────────────────────────────────────
 
   /** @internal */
@@ -1639,6 +1888,15 @@ export const Extensions = {
     return _groups
   },
 
+  /**
+   * Alias for {@link groups}.
+   *
+   * @returns {object}
+   */
+  getGroups() {
+    return this.groups()
+  },
+
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *

package/src/helpers.js

@@ -38,7 +38,16 @@ const rstrip = (line) => line.replace(/[ \t\r\n\f\v]+$/, '')
  */
 export function prepareSourceArray(data, trimEnd = true) {
   if (!data.length) return []
-  if (data[0].startsWith(BOM)) data[0] = data[0].slice(1)
+  if (data[0].startsWith(BOM)) {
+    data[0] = data[0].slice(1)
+  } else if (
+    data[0].charCodeAt(0) === 0xef &&
+    data[0].charCodeAt(1) === 0xbb &&
+    data[0].charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data[0] = data[0].slice(3)
+  }
   // Strip trailing \r to normalize Windows CRLF line endings (lines were split on \n, leaving \r).
   return trimEnd
     ? data.map(rstrip)
@@ -58,7 +67,16 @@ export function prepareSourceArray(data, trimEnd = true) {
  */
 export function prepareSourceString(data, trimEnd = true) {
   if (!data) return []
-  if (data.startsWith(BOM)) data = data.slice(1)
+  if (data.startsWith(BOM)) {
+    data = data.slice(1)
+  } else if (
+    data.charCodeAt(0) === 0xef &&
+    data.charCodeAt(1) === 0xbb &&
+    data.charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data = data.slice(3)
+  }
   // Normalize Windows CRLF to LF so that split('\n') does not leave trailing \r on each line.
   if (data.includes('\r'))
     data = data.replace(/\r\n/g, '\n').replace(/\r/g, '\n')

package/src/http_cache.js

@@ -0,0 +1,139 @@
+// HTTP cache system for URI fetching.
+//
+// Provides a pluggable caching layer for all HTTP(S) fetches performed during
+// document conversion (includes, images, readContents). Mirrors the behaviour
+// of Ruby's open-uri/cached mechanism activated by the `cache-uri` attribute.
+//
+// When `cache-uri` is set on the document:
+//   - If a cache has been registered via HttpCacheManager.setCache(), it is used.
+//   - Otherwise an ephemeral MemoryHttpCache is created for the duration of the
+//     conversion (keyed by Document instance via a WeakMap, GC'd with the doc).
+//
+// To implement a custom cache, extend HttpCache and override read(uri).
+
+/**
+ * Base HTTP cache class.
+ *
+ * The default implementation delegates directly to fetch() with no caching.
+ * Subclasses override read() to add caching behaviour.
+ */
+export class HttpCache {
+  /**
+   * Fetch content from a URI, optionally from a cache.
+   * @param {string} uri
+   * @returns {Promise<Response>}
+   */
+  async read(uri) {
+    return fetch(uri)
+  }
+}
+
+/**
+ * In-memory HTTP cache.
+ *
+ * Stores successful responses as ArrayBuffers keyed by URI. On a cache hit
+ * a synthetic Response is reconstructed from the stored data without touching
+ * the network. Non-OK responses (4xx, 5xx) are never cached.
+ *
+ * Safe as an ephemeral per-conversion cache or as a longer-lived process-level
+ * cache when registered via HttpCacheManager.setCache().
+ */
+export class MemoryHttpCache extends HttpCache {
+  /** @type {Map<string, {buffer: ArrayBuffer, status: number, statusText: string, headers: Record<string,string>}>} */
+  #cache = new Map()
+
+  async read(uri) {
+    const entry = this.#cache.get(uri)
+    if (entry) {
+      return new Response(entry.buffer.slice(0), {
+        status: entry.status,
+        statusText: entry.statusText,
+        headers: entry.headers,
+      })
+    }
+    const response = await fetch(uri)
+    if (response.ok) {
+      const buffer = await response.arrayBuffer()
+      const headers = Object.fromEntries(response.headers.entries())
+      this.#cache.set(uri, {
+        buffer,
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+      return new Response(buffer.slice(0), {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+      })
+    }
+    return response
+  }
+}
+
+/** @type {WeakMap<object, MemoryHttpCache>} */
+const _ephemeralCaches = new WeakMap()
+
+/**
+ * Singleton manager for the HTTP cache.
+ *
+ * Register a process-level cache:
+ *   HttpCacheManager.setCache(new MemoryHttpCache())
+ *   HttpCacheManager.setCache(new MyFileSystemCache('./cache'))
+ *   HttpCacheManager.setCache(null)  // revert to default ephemeral behaviour
+ *
+ * When no cache is registered and `cache-uri` is set, an ephemeral
+ * MemoryHttpCache is created per Document instance.
+ */
+export const HttpCacheManager = {
+  /** @type {HttpCache|null} */
+  _cache: null,
+
+  /**
+   * Register a cache to use for all conversions.
+   * Pass null to unregister and revert to the ephemeral default.
+   * @param {HttpCache|null} cache
+   */
+  setCache(cache) {
+    this._cache = cache
+  },
+
+  /**
+   * Return the registered process-level cache, or null if none is registered.
+   * @returns {HttpCache|null}
+   */
+  getCache() {
+    return this._cache
+  },
+
+  /**
+   * Return the cache to use for a specific document conversion.
+   *
+   * Returns the registered cache if one exists; otherwise creates (or reuses)
+   * an ephemeral MemoryHttpCache scoped to the document's lifetime via a WeakMap.
+   * @param {object} doc - the current Document instance
+   * @returns {HttpCache}
+   */
+  getCacheForDocument(doc) {
+    if (this._cache) return this._cache
+    let cache = _ephemeralCaches.get(doc)
+    if (!cache) {
+      cache = new MemoryHttpCache()
+      _ephemeralCaches.set(doc, cache)
+    }
+    return cache
+  },
+}
+
+/**
+ * Fetch a URI, routing through the HTTP cache when `cache-uri` is set on the document.
+ * @param {string} uri
+ * @param {object} doc - the current Document instance
+ * @returns {Promise<Response>}
+ */
+export function fetchUri(uri, doc) {
+  if (doc.hasAttribute('cache-uri')) {
+    return HttpCacheManager.getCacheForDocument(doc).read(uri)
+  }
+  return fetch(uri)
+}

package/src/index.js

@@ -10,6 +10,7 @@ import {
   RevisionInfo,
 } from './document.js'
 import { Logger, LoggerManager, MemoryLogger, NullLogger } from './logging.js'
+import { HttpCache, MemoryHttpCache, HttpCacheManager } from './http_cache.js'
 import { SafeMode, ContentModel } from './constants.js'
 import { Timings } from './timings.js'
 import { AbstractNode } from './abstract_node.js'
@@ -28,6 +29,18 @@ import {
   BlockMacroProcessor,
   Extensions,
 } from './extensions.js'
+
+// Re-export DSL interface types for TypeScript consumers.
+/**
+ * @typedef {import('./extensions.js').ProcessorDslInterface} ProcessorDslInterface
+ * @typedef {import('./extensions.js').DocumentProcessorDslInterface} DocumentProcessorDslInterface
+ * @typedef {import('./extensions.js').SyntaxProcessorDslInterface} SyntaxProcessorDslInterface
+ * @typedef {import('./extensions.js').IncludeProcessorDslInterface} IncludeProcessorDslInterface
+ * @typedef {import('./extensions.js').DocinfoProcessorDslInterface} DocinfoProcessorDslInterface
+ * @typedef {import('./extensions.js').BlockProcessorDslInterface} BlockProcessorDslInterface
+ * @typedef {import('./extensions.js').MacroProcessorDslInterface} MacroProcessorDslInterface
+ * @typedef {import('./extensions.js').InlineMacroProcessorDslInterface} InlineMacroProcessorDslInterface
+ */
 import {
   Converter,
   ConverterBase,
@@ -111,6 +124,9 @@ export {
   LoggerManager,
   MemoryLogger,
   NullLogger,
+  HttpCache,
+  MemoryHttpCache,
+  HttpCacheManager,
   SafeMode,
   ContentModel,
   Timings,

package/src/load.js

@@ -17,7 +17,7 @@
 
 import { SpaceDelimiterRx, EscapedSpaceRx } from './rx.js'
 import { NULL, BACKEND_ALIASES } from './constants.js'
-import { LoggerManager, NullLogger } from './logging.js'
+import { NullLogger, withLogger, getContextLogger } from './logging.js'
 import { basename, extname } from './helpers.js'
 import { Document } from './document.js'
 import { Converter } from './converter.js'
@@ -58,17 +58,23 @@ export async function load(input, options = {}) {
   // Shallow-copy options so we don't mutate the caller's object.
   options = Object.assign({}, options)
 
-  const timings = options.timings ?? null
-  if (timings) timings.start('read')
-
   // ── Logger override ───────────────────────────────────────────────────────
+  // When a logger option is supplied, run the conversion in an async-local
+  // context so the logger is scoped to this call only — no global mutation,
+  // which makes concurrent callers (e.g. parallel Deno tests) safe.
   if ('logger' in options) {
-    const logger = options.logger
-    if (logger !== LoggerManager.logger) {
-      LoggerManager.logger = logger ?? new NullLogger()
-    }
+    const newLogger = options.logger ?? new NullLogger()
+    delete options.logger
+    return withLogger(newLogger, () => _doLoad(input, options, newLogger))
   }
 
+  return _doLoad(input, options)
+}
+
+async function _doLoad(input, options, explicitLogger = null) {
+  const timings = options.timings ?? null
+  if (timings) timings.start('read')
+
   // ── Attributes normalisation ──────────────────────────────────────────────
   let attrs = options.attributes
   if (!attrs) {
@@ -100,11 +106,9 @@ export async function load(input, options = {}) {
       attrs.docname = basename(inputPath, docfilesuffix)
     }
     source = await _readStream(input)
-  } else if (
-    typeof input === 'object' &&
-    input?.constructor?.name === 'Buffer'
-  ) {
-    source = input.toString('utf8')
+  } else if (input instanceof Uint8Array) {
+    // Covers both Node.js Buffer (a Uint8Array subclass) and browser Uint8Array shims.
+    source = new TextDecoder('utf-8').decode(input)
   } else if (typeof input === 'string') {
     source = input
   } else if (Array.isArray(input)) {
@@ -167,6 +171,19 @@ export async function load(input, options = {}) {
   }
 
   if (timings) timings.record('parse')
+
+  // Persist the logger on the Document instance so that doc.convert()
+  // (called by convert.js after the async-local context ends) still routes
+  // logging through the caller-supplied logger.
+  // ALS provides it in Node.js/Deno; the explicit parameter covers browser fallback.
+  const contextLogger = getContextLogger() ?? explicitLogger
+  if (contextLogger) {
+    Object.defineProperty(doc, 'logger', {
+      get: () => contextLogger,
+      configurable: true,
+    })
+  }
+
   return doc
 }