@wdprlib/parser 3.2.0 → 4.1.0

package/src/parser/rules/block/module/listpages/url-resolver.ts

@@ -24,163 +24,6 @@
  * @module
  */
 
-import type { ListPagesDataRequirement, ListPagesQuery, NormalizedListPagesQuery } from "./types";
-import { normalizeQuery } from "./normalize";
-
-/**
- * Mapping of module attribute names to their corresponding `ListPagesQuery` keys
- * and expected value types. Only fields listed here support `@URL` resolution.
- */
-const URL_RESOLVABLE_FIELDS: ReadonlyArray<{
-  attr: string;
-  queryKey: keyof ListPagesQuery;
-  type: "string" | "number" | "boolean";
-}> = [
-  { attr: "offset", queryKey: "offset", type: "number" },
-  { attr: "limit", queryKey: "limit", type: "number" },
-  { attr: "per-page", queryKey: "perPage", type: "number" },
-  { attr: "order", queryKey: "order", type: "string" },
-  { attr: "tags", queryKey: "tags", type: "string" },
-  { attr: "category", queryKey: "category", type: "string" },
-  { attr: "parent", queryKey: "parent", type: "string" },
-  { attr: "range", queryKey: "range", type: "string" },
-  { attr: "name", queryKey: "name", type: "string" },
-  { attr: "fullname", queryKey: "fullname", type: "string" },
-  { attr: "created-at", queryKey: "createdAt", type: "string" },
-  { attr: "updated-at", queryKey: "updatedAt", type: "string" },
-  { attr: "created-by", queryKey: "createdBy", type: "string" },
-  { attr: "rating", queryKey: "rating", type: "string" },
-  { attr: "votes", queryKey: "votes", type: "string" },
-  { attr: "reverse", queryKey: "reverse", type: "boolean" },
-];
-
-/**
- * Parse URL path parameters like /offset/1/page2_limit/1
- * Returns a map of parameter name -> value
- */
-export function parseUrlParams(url: string): Map<string, string> {
-  const params = new Map<string, string>();
-  const parts = url.split("/").filter(Boolean);
-
-  // Skip the page name (first part), parse key/value pairs
-  for (let i = 1; i < parts.length - 1; i += 2) {
-    const key = parts[i];
-    const value = parts[i + 1];
-    if (key && value) {
-      params.set(key, value);
-    }
-  }
-
-  return params;
-}
-
-/**
- * Resolve @URL|default format with actual URL parameters
- *
- * @param rawValue - The raw attribute value (e.g., "@URL|0")
- * @param paramName - The parameter name (e.g., "offset")
- * @param urlParams - Parsed URL parameters
- * @param prefix - Optional URL attribute prefix (e.g., "page2")
- * @returns Resolved value
- */
-export function resolveUrlValue(
-  rawValue: string | undefined,
-  paramName: string,
-  urlParams: Map<string, string>,
-  prefix?: string,
-): string | undefined {
-  if (!rawValue) return undefined;
-
-  // Check for @URL or @URL|default format
-  if (!rawValue.startsWith("@URL")) {
-    return rawValue;
-  }
-
-  // Extract default value if present
-  const defaultValue = rawValue.includes("|") ? rawValue.split("|")[1] : undefined;
-
-  // Build the actual parameter name with prefix
-  const actualParamName = prefix ? `${prefix}_${paramName}` : paramName;
-
-  // Get from URL params or use default
-  return urlParams.get(actualParamName) ?? defaultValue;
-}
-
-/**
- * Resolve all `@URL` parameters and build a ListPagesQuery
- *
- * Takes a ListPagesDataRequirement and URL parameters, resolves all `@URL|default`
- * values, and returns a complete ListPagesQuery ready for database queries.
- *
- * @param requirement - The data requirement from AST extraction
- * @param urlParams - Parsed URL parameters (from parseUrlParams)
- * @returns Resolved ListPagesQuery
- *
- * @example
- * ```typescript
- * const urlParams = parseUrlParams("/page/scp-001/page2_offset/10/page2_limit/5");
- * const query = resolveQuery(requirement, urlParams);
- * // query.offset = 10, query.limit = 5 (if urlAttrPrefix = "page2")
- * ```
- */
-export function resolveQuery(
-  requirement: ListPagesDataRequirement,
-  urlParams: Map<string, string>,
-): ListPagesQuery {
-  const { query, rawAttributes, urlAttrPrefix } = requirement;
-  const resolved: ListPagesQuery = { ...query };
-
-  for (const field of URL_RESOLVABLE_FIELDS) {
-    const rawValue = rawAttributes[field.attr];
-    if (!rawValue) continue;
-
-    const resolvedValue = resolveUrlValue(rawValue, field.attr, urlParams, urlAttrPrefix);
-    if (resolvedValue === undefined) continue;
-
-    // Convert to appropriate type
-    switch (field.type) {
-      case "number": {
-        const num = parseInt(resolvedValue, 10);
-        if (!Number.isNaN(num)) {
-          (resolved as Record<string, unknown>)[field.queryKey] = num;
-        }
-        break;
-      }
-      case "boolean":
-        (resolved as Record<string, unknown>)[field.queryKey] =
-          resolvedValue === "true" || resolvedValue === "yes" || resolvedValue === "1";
-        break;
-      case "string":
-      default:
-        (resolved as Record<string, unknown>)[field.queryKey] = resolvedValue;
-        break;
-    }
-  }
-
-  return resolved;
-}
-
-/**
- * Resolve all `@URL` parameters and normalize the query
- *
- * Combines URL resolution with query normalization in a single call.
- * This is the recommended way to process ListPages queries for HPC.
- *
- * @param requirement - The data requirement from AST extraction
- * @param urlParams - Parsed URL parameters (from parseUrlParams)
- * @returns Normalized query with all `@URL` values resolved
- *
- * @example
- * ```typescript
- * const urlParams = parseUrlParams(window.location.pathname);
- * const normalizedQuery = resolveAndNormalizeQuery(requirement, urlParams);
- * // Ready for database query building
- * ```
- */
-export function resolveAndNormalizeQuery(
-  requirement: ListPagesDataRequirement,
-  urlParams: Map<string, string>,
-): NormalizedListPagesQuery {
-  const resolved = resolveQuery(requirement, urlParams);
-  return normalizeQuery(resolved);
-}
+export { parseUrlParams } from "./url-resolution/params";
+export { resolveAndNormalizeQuery, resolveQuery } from "./url-resolution/resolve";
+export { resolveUrlValue } from "./url-resolution/value";

package/src/parser/rules/block/module/listusers/compiler.ts

@@ -13,9 +13,8 @@
  */
 
 import type { ListUsersCompiledTemplate, ListUsersVariableContext } from "./types";
-
-/** Regex for matching `%%variable%%` patterns in the template. */
-const VARIABLE_REGEX = /%%([a-z_]+)%%/gi;
+import { createListUsersVariableGetter } from "./getters";
+import { LIST_USERS_VARIABLE_REGEX } from "./variables";
 
 /**
  * Compile a ListUsers template string into an executable function.
@@ -30,14 +29,14 @@ export function compileListUsersTemplate(template: string): ListUsersCompiledTem
   const parts: (string | ((ctx: ListUsersVariableContext) => string))[] = [];
   let lastIndex = 0;
 
-  for (const match of template.matchAll(VARIABLE_REGEX)) {
+  for (const match of template.matchAll(LIST_USERS_VARIABLE_REGEX)) {
     if (match.index !== undefined && match.index > lastIndex) {
       parts.push(template.slice(lastIndex, match.index));
     }
 
     const [, varName] = match;
     if (!varName) continue;
-    const getter = createVariableGetter(varName.toLowerCase());
+    const getter = createListUsersVariableGetter(varName.toLowerCase());
     parts.push(getter);
 
     lastIndex = match.index !== undefined ? match.index + match[0].length : lastIndex;
@@ -55,23 +54,3 @@ export function compileListUsersTemplate(template: string): ListUsersCompiledTem
     return result;
   };
 }
-
-/**
- * Create a getter function for a specific ListUsers variable.
- *
- * @param name - Lowercase variable name
- * @returns A function that extracts the variable's value from a ListUsersVariableContext.
- *          Unknown names return a function that always returns an empty string.
- */
-function createVariableGetter(name: string): (ctx: ListUsersVariableContext) => string {
-  switch (name) {
-    case "number":
-      return (ctx) => String(ctx.user.number);
-    case "title":
-      return (ctx) => ctx.user.title;
-    case "name":
-      return (ctx) => ctx.user.name;
-    default:
-      return () => "";
-  }
-}

package/src/parser/rules/block/module/listusers/extract.ts

@@ -11,12 +11,7 @@
 
 import type { ListUsersVariable } from "./types";
 import { compileListUsersTemplate } from "./compiler";
-
-/** Regex for matching `%%variable%%` patterns in ListUsers templates. */
-const VARIABLE_REGEX = /%%([a-z_]+)%%/gi;
-
-/** The complete list of recognized ListUsers template variables. */
-const KNOWN_VARIABLES: ListUsersVariable[] = ["number", "title", "name"];
+import { isListUsersVariable, LIST_USERS_VARIABLE_REGEX } from "./variables";
 
 /**
  * Extract the set of template variables referenced in a ListUsers template string.
@@ -30,12 +25,12 @@ const KNOWN_VARIABLES: ListUsersVariable[] = ["number", "title", "name"];
 export function extractListUsersVariables(template: string): ListUsersVariable[] {
   const variables = new Set<ListUsersVariable>();
 
-  for (const match of template.matchAll(VARIABLE_REGEX)) {
+  for (const match of template.matchAll(LIST_USERS_VARIABLE_REGEX)) {
     const [, varName] = match;
     if (!varName) continue;
     const normalized = varName.toLowerCase();
-    if (KNOWN_VARIABLES.includes(normalized as ListUsersVariable)) {
-      variables.add(normalized as ListUsersVariable);
+    if (isListUsersVariable(normalized)) {
+      variables.add(normalized);
     }
   }
 

package/src/parser/rules/block/module/listusers/getters.ts

@@ -0,0 +1,21 @@
+import type { ListUsersVariableContext } from "./types";
+
+type ListUsersVariableGetter = (ctx: ListUsersVariableContext) => string;
+
+/**
+ * Create a getter function for a specific ListUsers variable.
+ *
+ * Unknown names return a function that always returns an empty string.
+ */
+export function createListUsersVariableGetter(name: string): ListUsersVariableGetter {
+  switch (name) {
+    case "number":
+      return (ctx) => String(ctx.user.number);
+    case "title":
+      return (ctx) => ctx.user.title;
+    case "name":
+      return (ctx) => ctx.user.name;
+    default:
+      return () => "";
+  }
+}

package/src/parser/rules/block/module/listusers/variables.ts

@@ -0,0 +1,15 @@
+import type { ListUsersVariable } from "./types";
+
+/** Regex for matching `%%variable%%` patterns in ListUsers templates. */
+export const LIST_USERS_VARIABLE_REGEX: RegExp = /%%([a-z_]+)%%/gi;
+
+/** The complete set of recognized ListUsers template variables. */
+const KNOWN_VARIABLES: ReadonlySet<string> = new Set<ListUsersVariable>([
+  "number",
+  "title",
+  "name",
+]);
+
+export function isListUsersVariable(name: string): name is ListUsersVariable {
+  return KNOWN_VARIABLES.has(name);
+}

package/src/parser/rules/block/module/open.ts

@@ -0,0 +1,57 @@
+import type { ParseContext } from "../../types";
+import { parseAttributesRaw, parseBlockName } from "../utils";
+
+export interface ModuleOpenResult {
+  moduleName: string;
+  attrs: Record<string, string>;
+  pos: number;
+  consumed: number;
+}
+
+export function parseModuleOpen(ctx: ParseContext): ModuleOpenResult | null {
+  if (ctx.tokens[ctx.pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult || (nameResult.name !== "module" && nameResult.name !== "module654")) {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const nameToken = ctx.tokens[pos];
+  const moduleName =
+    nameToken?.type === "TEXT" || nameToken?.type === "IDENTIFIER" ? nameToken.value : "";
+  if (moduleName) {
+    pos++;
+    consumed++;
+  }
+
+  const attrResult = parseAttributesRaw(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  return {
+    moduleName,
+    attrs: attrResult.attrs,
+    pos,
+    consumed,
+  };
+}

package/src/parser/rules/block/module/resolution/contexts.ts

@@ -0,0 +1,78 @@
+import type { DataProvider } from "../types-common";
+import type {
+  CompiledTemplate,
+  ListPagesDataRequirement,
+  ListPagesExternalData,
+} from "../listpages/types";
+import type {
+  ListUsersCompiledTemplate,
+  ListUsersDataRequirement,
+  ListUsersExternalData,
+} from "../listusers/types";
+import type { ParseFunction } from "../listpages/resolve";
+import { buildListPagesDataMap, buildListUsersDataMap } from "./data-maps";
+
+/**
+ * Context for ListPages resolution.
+ */
+export interface ListPagesContext {
+  dataMap: Map<number, ListPagesExternalData>;
+  compiledTemplates: Map<number, CompiledTemplate>;
+  parse: ParseFunction;
+}
+
+/**
+ * Context for ListUsers resolution.
+ */
+export interface ListUsersContext {
+  dataMap: Map<number, ListUsersExternalData>;
+  compiledTemplates: Map<number, ListUsersCompiledTemplate>;
+  parse: ParseFunction;
+}
+
+export async function buildListPagesContext(
+  dataProvider: DataProvider,
+  requirements: ListPagesDataRequirement[],
+  compiledTemplates: Map<number, CompiledTemplate>,
+  parse: ParseFunction,
+  urlPath: string | undefined,
+): Promise<ListPagesContext | null> {
+  if (requirements.length === 0 || !dataProvider.fetchListPages) {
+    return null;
+  }
+
+  const dataMap = await buildListPagesDataMap(dataProvider, requirements, urlPath);
+
+  if (dataMap.size === 0) {
+    return null;
+  }
+
+  return {
+    dataMap,
+    compiledTemplates,
+    parse,
+  };
+}
+
+export async function buildListUsersContext(
+  dataProvider: DataProvider,
+  requirements: ListUsersDataRequirement[],
+  compiledTemplates: Map<number, ListUsersCompiledTemplate> | undefined,
+  parse: ParseFunction,
+): Promise<ListUsersContext | null> {
+  if (requirements.length === 0 || !dataProvider.fetchListUsers) {
+    return null;
+  }
+
+  const dataMap = await buildListUsersDataMap(dataProvider, requirements);
+
+  if (dataMap.size === 0) {
+    return null;
+  }
+
+  return {
+    dataMap,
+    compiledTemplates: compiledTemplates ?? new Map(),
+    parse,
+  };
+}

package/src/parser/rules/block/module/resolution/data-maps.ts

@@ -0,0 +1,39 @@
+import type { DataProvider } from "../types-common";
+import type { ListPagesDataRequirement, ListPagesExternalData } from "../listpages/types";
+import type { ListUsersDataRequirement, ListUsersExternalData } from "../listusers/types";
+import { parseUrlParams, resolveAndNormalizeQuery } from "../listpages/url-resolver";
+
+export async function buildListPagesDataMap(
+  dataProvider: DataProvider,
+  requirements: ListPagesDataRequirement[],
+  urlPath: string | undefined,
+): Promise<Map<number, ListPagesExternalData>> {
+  const dataMap = new Map<number, ListPagesExternalData>();
+  const urlParams = parseUrlParams(urlPath ?? "");
+
+  for (const req of requirements) {
+    const normalizedQuery = resolveAndNormalizeQuery(req, urlParams);
+    const data = await dataProvider.fetchListPages?.(normalizedQuery, req);
+    if (data) {
+      dataMap.set(req.id, data);
+    }
+  }
+
+  return dataMap;
+}
+
+export async function buildListUsersDataMap(
+  dataProvider: DataProvider,
+  requirements: ListUsersDataRequirement[],
+): Promise<Map<number, ListUsersExternalData>> {
+  const dataMap = new Map<number, ListUsersExternalData>();
+
+  for (const req of requirements) {
+    const data = await dataProvider.fetchListUsers?.(req);
+    if (data) {
+      dataMap.set(req.id, data);
+    }
+  }
+
+  return dataMap;
+}

package/src/parser/rules/block/module/resolution/dynamic-modules.ts

@@ -0,0 +1,93 @@
+import type { Element } from "@wdprlib/ast";
+import { isListPagesModule, resolveListPages } from "../listpages/resolve";
+import { isListUsersModule, resolveListUsers } from "../listusers/resolve";
+import { walkElements } from "../walk";
+import type { ListPagesContext, ListUsersContext } from "./contexts";
+
+export interface DynamicModuleContext {
+  listPages: ListPagesContext | null;
+  listUsers: ListUsersContext | null;
+  fetchListPagesProvided: boolean;
+  fetchListUsersProvided: boolean;
+}
+
+export interface DynamicModuleIds {
+  listPagesId: number;
+  listUsersId: number;
+}
+
+export interface DynamicModuleResolution {
+  handled: boolean;
+  elements: Element[];
+  ids: DynamicModuleIds;
+}
+
+export function resolveDynamicModuleElement(
+  element: Element,
+  ctx: DynamicModuleContext,
+  ids: DynamicModuleIds,
+): DynamicModuleResolution {
+  if (element.element !== "module") {
+    return { handled: false, elements: [element], ids };
+  }
+
+  if (isListPagesModule(element.data)) {
+    const elements: Element[] = [];
+    const listPagesId = ids.listPagesId;
+
+    if (ctx.listPages) {
+      const moduleData = ctx.listPages.dataMap.get(listPagesId);
+      const template = ctx.listPages.compiledTemplates.get(listPagesId);
+
+      if (moduleData && template) {
+        elements.push(...resolveListPages(element.data, moduleData, template, ctx.listPages.parse));
+      }
+    } else if (!ctx.fetchListPagesProvided) {
+      elements.push(element);
+    }
+
+    return {
+      handled: true,
+      elements,
+      ids: { ...ids, listPagesId: listPagesId + 1 },
+    };
+  }
+
+  if (isListUsersModule(element.data)) {
+    const elements: Element[] = [];
+    const listUsersId = ids.listUsersId;
+
+    if (ctx.listUsers) {
+      const moduleData = ctx.listUsers.dataMap.get(listUsersId);
+      const template = ctx.listUsers.compiledTemplates.get(listUsersId);
+
+      if (moduleData && template) {
+        elements.push(...resolveListUsers(element.data, moduleData, template, ctx.listUsers.parse));
+      }
+    } else if (!ctx.fetchListUsersProvided) {
+      elements.push(element);
+    }
+
+    return {
+      handled: true,
+      elements,
+      ids: { ...ids, listUsersId: listUsersId + 1 },
+    };
+  }
+
+  return { handled: false, elements: [element], ids };
+}
+
+export function countDynamicModules(elements: Element[]): DynamicModuleIds {
+  const counts: DynamicModuleIds = { listPagesId: 0, listUsersId: 0 };
+  walkElements(elements, (element) => {
+    if (element.element !== "module") return;
+
+    if (isListPagesModule(element.data)) {
+      counts.listPagesId++;
+    } else if (isListUsersModule(element.data)) {
+      counts.listUsersId++;
+    }
+  });
+  return counts;
+}

package/src/parser/rules/block/module/resolution/styles.ts

@@ -0,0 +1,53 @@
+import type { Element } from "@wdprlib/ast";
+import { STYLE_SLOT_PREFIX } from "@wdprlib/ast";
+import { mapElementChildren } from "../walk";
+import type { IfTagsData } from "../iftags/resolve";
+
+type IfTagsDataWithStyleSlot = IfTagsData & {
+  _styleSlot: number;
+};
+
+/**
+ * Collect and remove style elements from the AST.
+ *
+ * Unresolved `if-tags` elements receive style-slot placeholders so render-time
+ * iftags evaluation can preserve style order relative to already collected CSS.
+ */
+export function collectStyles(elements: Element[]): { elements: Element[]; styles: string[] } {
+  const styles: string[] = [];
+  const ctx = { nextSlotId: 0 };
+  const filtered = collectStylesFromElements(elements, styles, ctx);
+  return { elements: filtered, styles };
+}
+
+function collectStylesFromElements(
+  elements: Element[],
+  styles: string[],
+  ctx: { nextSlotId: number },
+): Element[] {
+  const result: Element[] = [];
+
+  for (const element of elements) {
+    if (element.element === "style") {
+      styles.push(element.data as string);
+      continue;
+    }
+
+    if (element.element === "if-tags") {
+      const slotId = ctx.nextSlotId++;
+      styles.push(`${STYLE_SLOT_PREFIX}${slotId}`);
+      const data: IfTagsDataWithStyleSlot = { ...(element.data as IfTagsData), _styleSlot: slotId };
+      result.push({
+        element: "if-tags",
+        data,
+      });
+      continue;
+    }
+
+    result.push(
+      mapElementChildren(element, (children) => collectStylesFromElements(children, styles, ctx)),
+    );
+  }
+
+  return result;
+}