@wdprlib/parser 2.0.10 → 2.1.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(exports_src, {
   text: () => import_ast5.text,
   resolveModules: () => resolveModules,
   resolveListUsers: () => resolveListUsers,
+  resolveIncludesAsync: () => resolveIncludesAsync,
   resolveIncludes: () => resolveIncludes,
   parseTags: () => parseTags,
   parseParent: () => parseParent,
@@ -9968,7 +9969,7 @@ function resolveIncludes(source, fetcher, options) {
   if (options?.settings && !options.settings.enablePageSyntax) {
     return source;
   }
-  const maxDepth = options?.maxDepth ?? 5;
+  const maxIterations = options?.maxIterations ?? 10;
   const cache = new Map;
   const cachedFetcher = (pageRef) => {
     const key = normalizePageKey(pageRef);
@@ -9984,7 +9985,29 @@ function resolveIncludes(source, fetcher, options) {
     cache.set(key, result);
     return result;
   };
-  return expandText(source, cachedFetcher, 0, maxDepth, []);
+  return expandIterative(source, cachedFetcher, maxIterations);
+}
+async function resolveIncludesAsync(source, fetcher, options) {
+  if (options?.settings && !options.settings.enablePageSyntax) {
+    return source;
+  }
+  const maxIterations = options?.maxIterations ?? 10;
+  const cache = new Map;
+  const cachedFetcher = async (pageRef) => {
+    const key = normalizePageKey(pageRef);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    let result;
+    try {
+      result = await fetcher(pageRef);
+    } catch {
+      result = null;
+    }
+    cache.set(key, result);
+    return result;
+  };
+  return expandIterativeAsync(source, cachedFetcher, maxIterations);
 }
 var INCLUDE_PATTERN = /^\[\[include\s([^\]]*(?:\](?!\])[^\]]*)*)\]\]/gim;
 function parseIncludeDirective(inner) {
@@ -10034,26 +10057,55 @@ function parseIncludeDirective(inner) {
   }
   return { location, variables };
 }
-function expandText(source, fetcher, depth, maxDepth, trace) {
-  if (depth >= maxDepth)
-    return source;
-  return source.replace(INCLUDE_PATTERN, (_match, inner) => {
-    const { location, variables } = parseIncludeDirective(inner);
-    const pageKey = normalizePageKey(location);
-    if (trace.includes(pageKey)) {
-      return `[[div class="error-block"]]
-Circular include detected: "${location.page}"
+function replaceOneInclude(_match, inner, fetcher) {
+  const { location, variables } = parseIncludeDirective(inner);
+  const content = fetcher(location);
+  if (content === null) {
+    return `[[div class="error-block"]]
+Page to be included "${location.page}" cannot be found!
 [[/div]]`;
-    }
-    const content = fetcher(location);
-    if (content === null) {
-      return `[[div class="error-block"]]
+  }
+  return substituteVariables(content, variables);
+}
+function expandIterative(source, fetcher, maxIterations) {
+  let current = source;
+  for (let i = 0;i < maxIterations; i++) {
+    const previous = current;
+    current = current.replace(INCLUDE_PATTERN, (_match, inner) => replaceOneInclude(_match, inner, fetcher));
+    if (current === previous)
+      break;
+  }
+  return current;
+}
+async function expandIterativeAsync(source, fetcher, maxIterations) {
+  let current = source;
+  for (let i = 0;i < maxIterations; i++) {
+    const previous = current;
+    const pattern = new RegExp(INCLUDE_PATTERN.source, INCLUDE_PATTERN.flags);
+    let result = "";
+    let lastPos = 0;
+    let match;
+    while ((match = pattern.exec(current)) !== null) {
+      const fullMatch = match[0];
+      const inner = match[1];
+      result += current.slice(lastPos, match.index);
+      const { location, variables } = parseIncludeDirective(inner);
+      const content = await fetcher(location);
+      if (content === null) {
+        result += `[[div class="error-block"]]
 Page to be included "${location.page}" cannot be found!
 [[/div]]`;
+      } else {
+        result += substituteVariables(content, variables);
+      }
+      lastPos = match.index + fullMatch.length;
     }
-    const substituted = substituteVariables(content, variables);
-    return expandText(substituted, fetcher, depth + 1, maxDepth, [...trace, pageKey]);
-  });
+    result += current.slice(lastPos);
+    current = result;
+    if (current === previous)
+      break;
+  }
+  return current;
 }
 function normalizePageKey(location) {
   const site = location.site ?? "";

package/dist/index.d.cts

@@ -859,21 +859,36 @@ import { PageRef, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
 */
 type IncludeFetcher = (pageRef: PageRef) => string | null;
 /**
-* Options for resolveIncludes
+* Async callback to fetch page content for include resolution.
+* Returns a promise of the wikitext source, or null if the page does not exist.
+*
+* @security The fetcher is called with user-provided page references.
+* Implementations should validate and sanitize page references before
+* using them in database queries or file system access.
+*/
+type AsyncIncludeFetcher = (pageRef: PageRef) => Promise<string | null>;
+/**
+* Options for resolveIncludes / resolveIncludesAsync
 */
 interface ResolveIncludesOptions {
-	/** Maximum recursion depth for nested includes (default: 5) */
-	maxDepth?: number;
+	/**
+	* Maximum number of expansion iterations (default: 10).
+	*
+	* Each iteration replaces all `[[include]]` directives in the current
+	* source with fetched content. Iteration stops when the source is
+	* unchanged or this limit is reached.
+	*/
+	maxIterations?: number;
 	/** Wikitext settings. If enablePageSyntax is false, includes are not expanded. */
 	settings?: WikitextSettings3;
 }
 /**
 * Expand all [[include]] directives in the source text.
 *
-* Include directives are treated as macro expansions: `[[include page]]`
-* is replaced with the fetched page content (after variable substitution).
-* The result is a single expanded text that can be parsed as a whole,
-* allowing block structures (like div) to span across include boundaries.
+* Uses Wikidot-compatible iterative expansion: each iteration replaces
+* all include directives in the current source with fetched (and
+* variable-substituted) content. Iteration continues until no further
+* changes occur or `maxIterations` is reached.
 *
 * @example
 * ```ts
@@ -883,6 +898,21 @@ interface ResolveIncludesOptions {
 */
 declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
 /**
+* Async version of {@link resolveIncludes}.
+*
+* Expand all [[include]] directives using an async fetcher, allowing
+* page content to be loaded from async sources such as databases.
+*
+* @example
+* ```ts
+* const expanded = await resolveIncludesAsync(source, async (ref) => {
+*   return await db.getPageContent(ref.page);
+* });
+* const ast = parse(expanded);
+* ```
+*/
+declare function resolveIncludesAsync(source: string, fetcher: AsyncIncludeFetcher, options?: ResolveIncludesOptions): Promise<string>;
+/**
 * Compile a ListUsers template string into an executable function.
 *
 * The template is split into alternating static strings and dynamic getter
@@ -981,4 +1011,4 @@ interface ResolveOptions {
 */
 declare function resolveModules(ast: SyntaxTree2, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree2>;
 import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-export { tokenize, text, resolveModules, resolveListUsers, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult2 as ParseResult, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AnchorTarget, Alignment, AlignType };
+export { tokenize, text, resolveModules, resolveListUsers, resolveIncludesAsync, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult2 as ParseResult, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };

package/dist/index.d.ts

@@ -859,21 +859,36 @@ import { PageRef, WikitextSettings as WikitextSettings3 } from "@wdprlib/ast";
 */
 type IncludeFetcher = (pageRef: PageRef) => string | null;
 /**
-* Options for resolveIncludes
+* Async callback to fetch page content for include resolution.
+* Returns a promise of the wikitext source, or null if the page does not exist.
+*
+* @security The fetcher is called with user-provided page references.
+* Implementations should validate and sanitize page references before
+* using them in database queries or file system access.
+*/
+type AsyncIncludeFetcher = (pageRef: PageRef) => Promise<string | null>;
+/**
+* Options for resolveIncludes / resolveIncludesAsync
 */
 interface ResolveIncludesOptions {
-	/** Maximum recursion depth for nested includes (default: 5) */
-	maxDepth?: number;
+	/**
+	* Maximum number of expansion iterations (default: 10).
+	*
+	* Each iteration replaces all `[[include]]` directives in the current
+	* source with fetched content. Iteration stops when the source is
+	* unchanged or this limit is reached.
+	*/
+	maxIterations?: number;
 	/** Wikitext settings. If enablePageSyntax is false, includes are not expanded. */
 	settings?: WikitextSettings3;
 }
 /**
 * Expand all [[include]] directives in the source text.
 *
-* Include directives are treated as macro expansions: `[[include page]]`
-* is replaced with the fetched page content (after variable substitution).
-* The result is a single expanded text that can be parsed as a whole,
-* allowing block structures (like div) to span across include boundaries.
+* Uses Wikidot-compatible iterative expansion: each iteration replaces
+* all include directives in the current source with fetched (and
+* variable-substituted) content. Iteration continues until no further
+* changes occur or `maxIterations` is reached.
 *
 * @example
 * ```ts
@@ -883,6 +898,21 @@ interface ResolveIncludesOptions {
 */
 declare function resolveIncludes(source: string, fetcher: IncludeFetcher, options?: ResolveIncludesOptions): string;
 /**
+* Async version of {@link resolveIncludes}.
+*
+* Expand all [[include]] directives using an async fetcher, allowing
+* page content to be loaded from async sources such as databases.
+*
+* @example
+* ```ts
+* const expanded = await resolveIncludesAsync(source, async (ref) => {
+*   return await db.getPageContent(ref.page);
+* });
+* const ast = parse(expanded);
+* ```
+*/
+declare function resolveIncludesAsync(source: string, fetcher: AsyncIncludeFetcher, options?: ResolveIncludesOptions): Promise<string>;
+/**
 * Compile a ListUsers template string into an executable function.
 *
 * The template is split into alternating static strings and dynamic getter
@@ -981,4 +1011,4 @@ interface ResolveOptions {
 */
 declare function resolveModules(ast: SyntaxTree2, dataProvider: DataProvider, options: ResolveOptions): Promise<SyntaxTree2>;
 import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
-export { tokenize, text, resolveModules, resolveListUsers, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult2 as ParseResult, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AnchorTarget, Alignment, AlignType };
+export { tokenize, text, resolveModules, resolveListUsers, resolveIncludesAsync, resolveIncludes, parseTags, parseParent, parseOrder, parseNumericSelector, parseDateSelector, parseCategory, parse, paragraph, normalizeQuery, listItemSubList, listItemElements, list, link, lineBreak, italics, isListUsersModule, horizontalRule, heading, extractListUsersVariables, extractDataRequirements, createToken, createSettings, createPosition, createPoint, container, compileTemplate, compileListUsersTemplate, bold, WikitextSettings4 as WikitextSettings, WikitextMode, Version2 as Version, VariableMap, VariableContext, UserInfo, TokenType, Token, TocEntry2 as TocEntry, TableRow, TableData, TableCell, TabData, SyntaxTree3 as SyntaxTree, SiteContext, STYLE_SLOT_PREFIX, ResolveOptions, ResolveIncludesOptions, Position2 as Position, Point, ParserOptions, Parser, ParseResult2 as ParseResult, ParseFunction, PageRef2 as PageRef, PageData, NormalizedTags, NormalizedParent, NormalizedOrder, NormalizedNumericSelector, NormalizedListPagesQuery, NormalizedDateSelector, NormalizedCategory, Module4 as Module, ListUsersVariableContext, ListUsersVariable, ListUsersUserData, ListUsersExternalData, ListUsersDataRequirement, ListUsersDataFetcher, ListUsersCompiledTemplate, ListType, ListPagesVariable, ListPagesQuery, ListPagesExternalData, ListPagesDataRequirement, ListPagesDataFetcher, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LexerOptions, Lexer, IncludeFetcher, ImageSource, HeadingLevel, Heading, HeaderType, FloatAlignment, ExtractionResult, Embed, Element6 as Element, DiagnosticSeverity, Diagnostic2 as Diagnostic, DefinitionListItem, DateItem, DataRequirements, DataProvider, DEFAULT_SETTINGS, ContainerType, ContainerData, CompiledTemplate, CollapsibleData, CodeBlockData2 as CodeBlockData, ClearFloat, AttributeMap, AsyncIncludeFetcher, AnchorTarget, Alignment, AlignType };

package/dist/index.js

@@ -9913,7 +9913,7 @@ function resolveIncludes(source, fetcher, options) {
   if (options?.settings && !options.settings.enablePageSyntax) {
     return source;
   }
-  const maxDepth = options?.maxDepth ?? 5;
+  const maxIterations = options?.maxIterations ?? 10;
   const cache = new Map;
   const cachedFetcher = (pageRef) => {
     const key = normalizePageKey(pageRef);
@@ -9929,7 +9929,29 @@ function resolveIncludes(source, fetcher, options) {
     cache.set(key, result);
     return result;
   };
-  return expandText(source, cachedFetcher, 0, maxDepth, []);
+  return expandIterative(source, cachedFetcher, maxIterations);
+}
+async function resolveIncludesAsync(source, fetcher, options) {
+  if (options?.settings && !options.settings.enablePageSyntax) {
+    return source;
+  }
+  const maxIterations = options?.maxIterations ?? 10;
+  const cache = new Map;
+  const cachedFetcher = async (pageRef) => {
+    const key = normalizePageKey(pageRef);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    let result;
+    try {
+      result = await fetcher(pageRef);
+    } catch {
+      result = null;
+    }
+    cache.set(key, result);
+    return result;
+  };
+  return expandIterativeAsync(source, cachedFetcher, maxIterations);
 }
 var INCLUDE_PATTERN = /^\[\[include\s([^\]]*(?:\](?!\])[^\]]*)*)\]\]/gim;
 function parseIncludeDirective(inner) {
@@ -9979,26 +10001,55 @@ function parseIncludeDirective(inner) {
   }
   return { location, variables };
 }
-function expandText(source, fetcher, depth, maxDepth, trace) {
-  if (depth >= maxDepth)
-    return source;
-  return source.replace(INCLUDE_PATTERN, (_match, inner) => {
-    const { location, variables } = parseIncludeDirective(inner);
-    const pageKey = normalizePageKey(location);
-    if (trace.includes(pageKey)) {
-      return `[[div class="error-block"]]
-Circular include detected: "${location.page}"
+function replaceOneInclude(_match, inner, fetcher) {
+  const { location, variables } = parseIncludeDirective(inner);
+  const content = fetcher(location);
+  if (content === null) {
+    return `[[div class="error-block"]]
+Page to be included "${location.page}" cannot be found!
 [[/div]]`;
-    }
-    const content = fetcher(location);
-    if (content === null) {
-      return `[[div class="error-block"]]
+  }
+  return substituteVariables(content, variables);
+}
+function expandIterative(source, fetcher, maxIterations) {
+  let current = source;
+  for (let i = 0;i < maxIterations; i++) {
+    const previous = current;
+    current = current.replace(INCLUDE_PATTERN, (_match, inner) => replaceOneInclude(_match, inner, fetcher));
+    if (current === previous)
+      break;
+  }
+  return current;
+}
+async function expandIterativeAsync(source, fetcher, maxIterations) {
+  let current = source;
+  for (let i = 0;i < maxIterations; i++) {
+    const previous = current;
+    const pattern = new RegExp(INCLUDE_PATTERN.source, INCLUDE_PATTERN.flags);
+    let result = "";
+    let lastPos = 0;
+    let match;
+    while ((match = pattern.exec(current)) !== null) {
+      const fullMatch = match[0];
+      const inner = match[1];
+      result += current.slice(lastPos, match.index);
+      const { location, variables } = parseIncludeDirective(inner);
+      const content = await fetcher(location);
+      if (content === null) {
+        result += `[[div class="error-block"]]
 Page to be included "${location.page}" cannot be found!
 [[/div]]`;
+      } else {
+        result += substituteVariables(content, variables);
+      }
+      lastPos = match.index + fullMatch.length;
     }
-    const substituted = substituteVariables(content, variables);
-    return expandText(substituted, fetcher, depth + 1, maxDepth, [...trace, pageKey]);
-  });
+    result += current.slice(lastPos);
+    current = result;
+    if (current === previous)
+      break;
+  }
+  return current;
 }
 function normalizePageKey(location) {
   const site = location.site ?? "";
@@ -10227,6 +10278,7 @@ export {
   text,
   resolveModules,
   resolveListUsers,
+  resolveIncludesAsync,
   resolveIncludes,
   parseTags,
   parseParent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdprlib/parser",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "description": "Parser for Wikidot markup",
   "keywords": [
     "ast",