@opencraw/core 0.1.3 → 0.1.4

package/dist/src/xml-document/xml-parser.client.d.ts

@@ -0,0 +1,49 @@
+/** A parsed document, as the XPath engine sees it. */
+export type XmlNode = Node;
+/**
+ * Parses XML strictly but safely: a malformed document is an error naming
+ * the URL and the line; entities a DOCTYPE declares are never expanded (no
+ * "billion laughs") and nothing external is ever fetched (no XXE), they stay
+ * as they are.
+ *
+ * @param xml - The document text.
+ * @param where - The URL or id, for messages.
+ * @returns The document.
+ * @throws Error when the text is not well-formed XML.
+ */
+export declare function parseXml(xml: string, where: string): Document;
+/**
+ * HTML as an XML document, for XPath on fetched pages: parsed the way a
+ * browser parses it (a forgiving HTML5 parser that inserts `<tbody>` and
+ * closes what the page left open), without namespaces, so `//table/tbody/tr`
+ * finds what it finds on the live page.
+ *
+ * @param html - A page or a fragment.
+ * @returns The document.
+ */
+export declare function htmlAsXml(html: string): Document;
+/**
+ * A copy of a document with every namespace dropped: elements and attributes
+ * keep their local names, `xmlns` declarations go. What `ignoreNamespaces`
+ * queries run on: `//entry/title` instead of `//atom:entry/atom:title`.
+ *
+ * @param document - A parsed document.
+ * @returns The copy.
+ */
+export declare function withoutNamespaces(document: Document): Document;
+/**
+ * A node as markup: the element with its children (`outer`), or its children only.
+ *
+ * @param node - A node.
+ * @param outer - Whether to include the node itself.
+ * @returns The markup.
+ */
+export declare function serializeXml(node: Node, outer: boolean): string;
+/**
+ * The text of an XML body, gunzipped first when it is gzip (a `sitemap.xml.gz`).
+ *
+ * @param bytes - The body.
+ * @returns The bytes to decode.
+ */
+export declare function gunzipIfNeeded(bytes: Uint8Array): Uint8Array;
+//# sourceMappingURL=xml-parser.client.d.ts.map

package/dist/src/xml-document/xpath.algorithm.d.ts

@@ -0,0 +1,30 @@
+import type { Take } from '../selection/index.js';
+/** An XPath result: a node, or what a function such as `count()` or `string()` gives. */
+export type XpathValue = Node | string | number | boolean;
+export interface XpathOptions {
+    /** Prefix to URI, for queries on namespaced documents (`atom: http://www.w3.org/2005/Atom`). */
+    namespaces?: Record<string, string>;
+    /** Drop the document's namespaces first, so plain names match (`//entry/title`). */
+    ignoreNamespaces?: boolean;
+}
+/**
+ * Runs an XPath 1.0 query on a parsed document. Prefixes the root element
+ * declares are known without being listed; a default namespace has no
+ * prefix, so name one in `namespaces` or use `ignoreNamespaces`.
+ *
+ * @param document - The document.
+ * @param expression - The query.
+ * @param options - Namespaces.
+ * @returns Every node selected, or the one value a function returned.
+ * @throws Error naming the query when it does not parse or uses an unknown prefix.
+ */
+export declare function selectXpath(document: Document, expression: string, options?: XpathOptions): XpathValue[];
+/**
+ * The value of an XPath result.
+ *
+ * @param value - A node or a function result.
+ * @param take - `text` (whitespace collapsed), `html` (the node's inner markup), `json` (its outer markup), `value` (its text as is), `attr:<name>`.
+ * @returns The value; `undefined` for a missing attribute.
+ */
+export declare function takeFromXml(value: XpathValue, take: Take): unknown;
+//# sourceMappingURL=xpath.algorithm.d.ts.map

package/dist/step-flow/block-rule.policy.d.ts

@@ -0,0 +1,21 @@
+import type { BlockRule } from '../recipe-schema/index.js';
+import { BlockedError } from './blocked.error.js';
+/** A block unless a recipe says otherwise: forbidden, rate limited, or an AWS WAF challenge (IMDb answers 202 with it). */
+export declare const DEFAULT_BLOCK_RULE: BlockRule;
+/** The parts of a response a block rule reads. The body is read only when the rule has a `text` condition. */
+export interface ObservedResponse {
+    url: string;
+    status: number;
+    /** Header names in lower case, as Playwright reports them. */
+    headers: Record<string, string>;
+    text?: () => Promise<string>;
+}
+/**
+ * Whether a response is a block.
+ *
+ * @param response - What came back.
+ * @param rule - The recipe's `session.blockedWhen`; `DEFAULT_BLOCK_RULE` when omitted.
+ * @returns The error to throw, or `undefined` when the response is not a block.
+ */
+export declare function detectBlock(response: ObservedResponse, rule?: BlockRule): Promise<BlockedError | undefined>;
+//# sourceMappingURL=block-rule.policy.d.ts.map

package/dist/step-flow/blocked.error.d.ts

@@ -0,0 +1,9 @@
+/** A response the recipe's `session.blockedWhen` rule (or the default one) says is the site refusing the crawl. */
+export declare class BlockedError extends Error {
+    readonly url: string;
+    readonly status: number;
+    readonly reason: string;
+    readonly name = "BlockedError";
+    constructor(url: string, status: number, reason: string);
+}
+//# sourceMappingURL=blocked.error.d.ts.map

package/dist/step-flow/for-each.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { ForEachStep } from '../recipe-schema/index.js';
+import type { EmitOutcome, StepWalk } from './run-steps.use-case.js';
+/**
+ * Runs a body once per item of a list (`over`), or once per live element
+ * matching `selector`, each in a fresh child scope with the item bound under
+ * `as`; emits a record per iteration when asked.
+ *
+ * With a concurrent gate, iterations of a list run as permits allow and
+ * records come out in completion order; without one, in list order. In web
+ * mode each parallel iteration runs in a tab of its own (`runner.fork`); a
+ * loop over live elements stays sequential, since its elements live on one page.
+ *
+ * @param step - The forEach step.
+ * @param scope - The scope the list lives in.
+ * @param walk - Runs a step list; also carries the emit callback.
+ * @returns `stop` when the crawl reached its record limit.
+ */
+export declare function runForEach(step: ForEachStep, scope: ExtractionScope, walk: StepWalk): Promise<EmitOutcome>;
+//# sourceMappingURL=for-each.use-case.d.ts.map

package/dist/step-flow/host-throttle.policy.d.ts

@@ -0,0 +1,49 @@
+/** How gently one site is crawled. */
+export interface HostRule {
+    /** Minimum time between two request starts to the site, whatever recipe sends them. */
+    delayMs?: number;
+    /** Requests to the site in flight at once. */
+    concurrency?: number;
+}
+/**
+ * The crawler's politeness towards each site, across every recipe and run it
+ * executes: a default rule for any host, and rules by domain (`example.com`
+ * also covers `www.example.com`; the longest match wins).
+ */
+export interface ThrottleConfig extends HostRule {
+    domains?: Record<string, HostRule>;
+}
+/**
+ * Spaces and bounds requests per site, shared by every recipe of a crawler,
+ * so two recipes (or two parallel iterations) that hit one site add up to one
+ * polite client rather than two. A recipe's own `limits.delayMs` still applies
+ * on top, per recipe.
+ *
+ * Like a single-lane bridge with a traffic light: whoever arrives waits for
+ * the car ahead to be far enough, and for a free lane.
+ */
+export declare class HostThrottle {
+    private readonly config;
+    private readonly buckets;
+    private readonly domains;
+    constructor(config?: ThrottleConfig);
+    private bucketFor;
+    /** Whether any rule can hold a request back. */
+    get active(): boolean;
+    /**
+     * Waits until a request to `url` may start, then holds one of its site's
+     * lanes until the returned release is called.
+     *
+     * @param url - Where the request goes; anything but `http(s):` passes at once.
+     * @returns The release: call it once, when the response arrived or the request failed.
+     */
+    slot(url: string): Promise<() => void>;
+    /**
+     * Holds every request to the site of `url` back until `untilMs` (a `Retry-After`).
+     *
+     * @param url - A URL of the site.
+     * @param untilMs - An epoch time.
+     */
+    pause(url: string, untilMs: number): void;
+}
+//# sourceMappingURL=host-throttle.policy.d.ts.map

package/dist/step-flow/index.d.ts

@@ -0,0 +1,15 @@
+export { runSteps } from './run-steps.use-case.js';
+export type { StepWalkOptions, EmitOutcome } from './run-steps.use-case.js';
+export type { StepRunner, NextPageResult } from './step-runner.contract.js';
+export { disposeQuietly } from './step-runner.contract.js';
+export { StepFailure, NoMatchError } from './step-failure.error.js';
+export { resolveErrorPolicy, backoffFor, sleep } from './retry.policy.js';
+export { RunGate } from './run-gate.policy.js';
+export { HostThrottle } from './host-throttle.policy.js';
+export { withTransportRetry, resolveRetryRule, transientError, retryDelay, DEFAULT_RETRY_RULE, RETRY_STATUSES } from './transport-retry.policy.js';
+export type { ResolvedRetryRule, Transient, TransportAttempt, RetryContext } from './transport-retry.policy.js';
+export type { HostRule, ThrottleConfig } from './host-throttle.policy.js';
+export { BlockedError } from './blocked.error.js';
+export { detectBlock, DEFAULT_BLOCK_RULE } from './block-rule.policy.js';
+export type { ObservedResponse } from './block-rule.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/step-flow/paginate.use-case.d.ts

@@ -0,0 +1,17 @@
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { PaginateStep } from '../recipe-schema/index.js';
+import type { EmitOutcome, StepWalk } from './run-steps.use-case.js';
+/**
+ * Runs a body once per page, each in a fresh child scope, then asks the runner
+ * for the next page until there is none, `until` renders truthy, or `maxPages`
+ * is reached.
+ *
+ * The runner reports the visit of each new page; this only steers.
+ *
+ * @param step - The paginate step.
+ * @param scope - The scope to page in; its page URL advances with each page.
+ * @param walk - Runs a step list; carries the runner and the emit callback.
+ * @returns `stop` when the crawl reached its record limit.
+ */
+export declare function runPaginate(step: PaginateStep, scope: ExtractionScope, walk: StepWalk): Promise<EmitOutcome>;
+//# sourceMappingURL=paginate.use-case.d.ts.map

package/dist/step-flow/retry.policy.d.ts

@@ -0,0 +1,21 @@
+import type { ErrorPolicy, InputRecipe, Step } from '../recipe-schema/index.js';
+/**
+ * The policy for a failing step: the step's own, else the recipe's, else `fail`.
+ *
+ * @param step - The step that failed.
+ * @param recipe - Its recipe.
+ * @returns The policy to apply.
+ */
+export declare function resolveErrorPolicy(step: Step, recipe: Pick<InputRecipe, 'onError'>): ErrorPolicy;
+/**
+ * How long to wait before a retry: linear backoff.
+ *
+ * @param policy - A retry policy.
+ * @param attempt - The attempt about to be made, starting at 2.
+ * @returns Milliseconds.
+ */
+export declare function backoffFor(policy: Extract<ErrorPolicy, {
+    policy: 'retry';
+}>, attempt: number): number;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=retry.policy.d.ts.map

package/dist/step-flow/run-gate.policy.d.ts

@@ -0,0 +1,50 @@
+import type { HostThrottle } from './host-throttle.policy.js';
+/**
+ * What bounds a recipe run: how many `forEach` iterations may be in flight and
+ * how close together requests may start. One gate per recipe run, shared by
+ * every loop in it, so nested loops never multiply the limit.
+ *
+ * Permits go to the outermost concurrent loop: a loop that runs inside an
+ * iteration already holding a permit runs its body sequentially (see `nested`),
+ * which keeps the total at `permits` and cannot deadlock.
+ */
+export declare class RunGate {
+    readonly permits: number;
+    readonly minIntervalMs: number;
+    readonly hosts?: HostThrottle | undefined;
+    private readonly shared?;
+    private inFlight;
+    private readonly waiting;
+    private lastStart;
+    /**
+     * @param permits - Iterations allowed in flight; 1 is sequential.
+     * @param minIntervalMs - Minimum time between two request starts across the run.
+     * @param hosts - The crawler's per-site throttle, shared with every other recipe.
+     * @param shared - The throttle state to share (internal: `nested` gates keep their parent's).
+     */
+    constructor(permits: number, minIntervalMs: number, hosts?: HostThrottle | undefined, shared?: RunGate | undefined);
+    /** Whether this gate lets more than one iteration run at once. */
+    get concurrent(): boolean;
+    /**
+     * Takes a permit, waiting for one when all are in flight.
+     *
+     * @returns The release; call it exactly once, when the iteration ends.
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Waits until a request may start: `minIntervalMs` after the previous start,
+     * whichever loop started it. Returns at once when the interval has passed.
+     */
+    throttle(): Promise<void>;
+    /**
+     * Waits until a request to `url` may start: the recipe's interval, then its
+     * site's turn in the crawler's per-site throttle.
+     *
+     * @param url - Where the request goes.
+     * @returns The release of the site's lane: call it once the response arrived or the request failed.
+     */
+    request(url: string): Promise<() => void>;
+    /** The gate for a body running inside an iteration that holds a permit: sequential, same throttle. */
+    nested(): RunGate;
+}
+//# sourceMappingURL=run-gate.policy.d.ts.map

package/dist/step-flow/run-steps.use-case.d.ts

@@ -0,0 +1,39 @@
+import type { EventBus } from '../crawl-events/index.js';
+import type { ExtractionScope } from '../extraction-scope/index.js';
+import type { HookRegistry } from '../hooks/index.js';
+import type { InputRecipe, Step } from '../recipe-schema/index.js';
+import type { RunGate } from './run-gate.policy.js';
+import type { StepRunner } from './step-runner.contract.js';
+/** Whether the walk goes on after a record was emitted. */
+export type EmitOutcome = 'continue' | 'stop';
+/** Everything a step walk needs. */
+export interface StepWalkOptions {
+    recipe: InputRecipe;
+    runner: StepRunner;
+    hooks: HookRegistry;
+    events: EventBus;
+    /** Called with the scope to snapshot for each record; `stop` ends the walk. */
+    onEmit: (scope: ExtractionScope, output?: string) => Promise<EmitOutcome>;
+    /** Bounds concurrency and request rate; absent means sequential and unthrottled. */
+    gate?: RunGate;
+}
+/** The walk as the control-flow steps see it: options plus the current path. */
+export interface StepWalk extends StepWalkOptions {
+    path: string;
+    /** Runs a nested step list; `overrides` replace walk options for that list (a sequential gate inside a concurrent iteration). */
+    runSteps: (steps: readonly Step[], scope: ExtractionScope, path: string, overrides?: Partial<StepWalkOptions>) => Promise<EmitOutcome>;
+}
+/**
+ * Walks a step list in order. Control flow (`forEach`, `if`, `paginate`, `emit`,
+ * `set`, `hook`, `when`, error policies) is handled here; leaf steps go to the
+ * runner. Mode-agnostic: the same walk drives a browser page or an HTTP context.
+ *
+ * @param steps - The steps.
+ * @param scope - The scope to run in.
+ * @param options - Recipe, runner, hooks, events and the emit callback.
+ * @param path - Where these steps are, for messages and events.
+ * @returns `stop` when the emit callback asked to stop.
+ * @throws StepFailure when a step fails under the `fail` policy.
+ */
+export declare function runSteps(steps: readonly Step[], scope: ExtractionScope, options: StepWalkOptions, path?: string): Promise<EmitOutcome>;
+//# sourceMappingURL=run-steps.use-case.d.ts.map

package/dist/step-flow/step-failure.error.d.ts

@@ -0,0 +1,14 @@
+/** A step that failed under the `fail` policy: the recipe stops here. */
+export declare class StepFailure extends Error {
+    readonly stepPath: string;
+    readonly stepType: string;
+    readonly name = "StepFailure";
+    constructor(stepPath: string, stepType: string, cause: unknown);
+}
+/** A single `extract` that matched nothing. */
+export declare class NoMatchError extends Error {
+    readonly selector: string;
+    readonly name = "NoMatchError";
+    constructor(selector: string);
+}
+//# sourceMappingURL=step-failure.error.d.ts.map

package/dist/step-flow/step-runner.contract.d.ts

@@ -0,0 +1,52 @@
+import type { ExtractionScope, LiveElement } from '../extraction-scope/index.js';
+import type { PaginateNext, Step } from '../recipe-schema/index.js';
+import type { BlockedError } from './blocked.error.js';
+/**
+ * Disposes a runner, ignoring a failure: a tab whose browser already went
+ * away (a rotation, a crash) has nothing left to close.
+ *
+ * @param runner - The runner.
+ */
+export declare function disposeQuietly(runner: StepRunner): Promise<void>;
+/** What `paginate` learns from the runner after a page body ran. */
+export type NextPageResult = 
+/** The next page is at this URL (the runner already navigated in web mode). */
+{
+    kind: 'url';
+    url: string;
+} | 
+/** A value to bind in the next page's scope under `name` (a cursor, a token). */
+{
+    kind: 'value';
+    name: string;
+    value: unknown;
+} | 
+/** There is no next page. */
+null;
+/**
+ * The mode-specific half of step execution. `step-flow` walks the tree and
+ * owns control flow; a runner executes leaf steps against a page or a request
+ * context. Runners never mutate scope bindings other than through this contract.
+ */
+export interface StepRunner {
+    /** Runs one leaf step (not forEach, paginate, emit, set or hook). */
+    runLeaf: (step: Step, scope: ExtractionScope) => Promise<void>;
+    /** Finds (and in web mode reaches) the next page. */
+    nextPage: (next: PaginateNext, scope: ExtractionScope) => Promise<NextPageResult>;
+    /** Snapshots every element matching a rendered selector, for `forEach` over `selector`. Web mode only. */
+    elements?: (selector: string, scope: ExtractionScope) => Promise<LiveElement[]>;
+    /**
+     * Called when a step is blocked. `true` means the runner now reaches the
+     * network another way (a new access lease) and the step should run again;
+     * `false` means it cannot, and the block fails the step like any error.
+     */
+    rotate?: (error: BlockedError) => Promise<boolean>;
+    /**
+     * A runner of its own for one parallel `forEach` iteration: a new tab in the
+     * same browser context (same cookies, its own page), disposed when the
+     * iteration ends. Web mode; an api runner is shared as it is.
+     */
+    fork?: () => Promise<StepRunner>;
+    dispose: () => Promise<void>;
+}
+//# sourceMappingURL=step-runner.contract.d.ts.map

package/dist/step-flow/transport-retry.policy.d.ts

@@ -0,0 +1,76 @@
+import type { EventBus } from '../crawl-events/index.js';
+import type { RetryRule } from '../recipe-schema/index.js';
+import type { RunGate } from './run-gate.policy.js';
+/** A retry rule with every default filled in. */
+export type ResolvedRetryRule = Required<RetryRule>;
+/** Statuses a server uses for "not now": timeout, too early, too many requests, and the 5xx that pass. */
+export declare const RETRY_STATUSES: readonly number[];
+/** Three tries, one second then two apart, never a wait over 30 seconds. */
+export declare const DEFAULT_RETRY_RULE: ResolvedRetryRule;
+/** Why an attempt may be worth repeating, and the server's own `Retry-After`, if it sent one. */
+export interface Transient {
+    reason: string;
+    retryAfter?: string;
+}
+/** One try of a request, and how to tell a passing failure in what it gave. */
+export interface TransportAttempt<T> {
+    run: () => Promise<T>;
+    /** A transient problem in the outcome (a retry status, a connection error), or `undefined` when the outcome stands. */
+    problem: (outcome: {
+        value: T;
+    } | {
+        error: unknown;
+    }) => Transient | undefined;
+}
+export interface RetryContext {
+    recipeId: string;
+    gate: RunGate;
+    events: EventBus;
+    rule: ResolvedRetryRule;
+}
+/**
+ * The retry rule a recipe runs with: its `limits.retry` over the crawler's
+ * default over `DEFAULT_RETRY_RULE`.
+ *
+ * @param own - The recipe's `limits.retry`.
+ * @param crawler - The crawler's `retry` option.
+ * @returns The rule.
+ */
+export declare function resolveRetryRule(own?: RetryRule, crawler?: RetryRule): ResolvedRetryRule;
+/**
+ * Whether an error is a connection failure worth another try.
+ *
+ * @param error - What the request threw.
+ * @returns The reason, or `undefined`.
+ */
+export declare function transientError(error: unknown): Transient | undefined;
+/**
+ * How long to wait before attempt `attempt + 1`: the server's `Retry-After`
+ * when it gave one, else `backoffMs` doubling per attempt with a little
+ * jitter; `undefined` when the server asks for longer than `maxDelayMs` (it
+ * means "come back much later", which a crawl cannot wait for).
+ *
+ * @param rule - The retry rule.
+ * @param attempt - The attempt that just failed, from 1.
+ * @param retryAfter - The `Retry-After` header: seconds, or an HTTP date.
+ * @param now - The current time, for dates.
+ * @returns Milliseconds, or `undefined` for no retry.
+ */
+export declare function retryDelay(rule: ResolvedRetryRule, attempt: number, retryAfter?: string, now?: number): number | undefined;
+/**
+ * Sends a request through the gate (the recipe's rate, the site's lane), and
+ * sends it again after a pause while it fails in a passing way, up to
+ * `rule.attempts` tries in all. A `Retry-After` holds back every request to
+ * that site, not only this one. Each retry is reported as `request:retry`.
+ *
+ * Like redialling a busy number: wait a moment, dial again, give up after a
+ * few tries; and if the other end said "call back in a minute", wait that minute.
+ *
+ * @param url - Where the request goes.
+ * @param attempt - How to send it and how to judge the outcome.
+ * @param context - The recipe, gate, events and rule.
+ * @returns What the last try gave.
+ * @throws What the last try threw.
+ */
+export declare function withTransportRetry<T>(url: string, attempt: TransportAttempt<T>, context: RetryContext): Promise<T>;
+//# sourceMappingURL=transport-retry.policy.d.ts.map

package/dist/template/expression.algorithm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A small expression language for `{{ }}` placeholders: literals, paths,
+ * arithmetic, comparison, logic, `??`, `a ? b : c` and a fixed set of
+ * functions. It is parsed into a tree and walked; nothing is ever compiled or
+ * evaluated as JavaScript, and a path can only read own properties of plain
+ * data, so `constructor`, `__proto__` and friends resolve to nothing.
+ */
+import type { Lookup } from './value-text.algorithm.js';
+export type Expression = {
+    kind: 'literal';
+    value: unknown;
+} | {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'unary';
+    op: '-' | '!';
+    operand: Expression;
+} | {
+    kind: 'binary';
+    op: string;
+    left: Expression;
+    right: Expression;
+} | {
+    kind: 'ternary';
+    test: Expression;
+    consequent: Expression;
+    alternate: Expression;
+} | {
+    kind: 'call';
+    name: string;
+    args: Expression[];
+};
+/** The names an expression may call. */
+export declare const EXPRESSION_FUNCTIONS: readonly string[];
+/**
+ * Parses an expression, with a small cache since templates render per iteration.
+ *
+ * @param source - The text inside the placeholder.
+ * @returns The tree.
+ * @throws Error naming the position of the first problem.
+ */
+export declare function parseExpression(source: string): Expression;
+/**
+ * Evaluates a tree against a lookup. A function found where data is expected
+ * counts as `undefined`, so nothing callable ever leaks out of the scope.
+ *
+ * @param expression - The tree.
+ * @param lookup - Resolves a path.
+ * @returns The value.
+ */
+export declare function evaluateExpression(expression: Expression, lookup: Lookup): unknown;
+//# sourceMappingURL=expression.algorithm.d.ts.map

package/dist/template/index.d.ts

@@ -0,0 +1,7 @@
+export { getPath, setPath, segmentsOf } from './value-path.algorithm.js';
+export { render, renderDeep, renderText, resolve, hasPlaceholder } from './template.algorithm.js';
+export { isTruthy, stringify } from './value-text.algorithm.js';
+export { parseExpression, evaluateExpression, EXPRESSION_FUNCTIONS } from './expression.algorithm.js';
+export type { Expression } from './expression.algorithm.js';
+export type { Lookup } from './value-text.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/template/template.algorithm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `{{ }}` interpolation for recipe strings. A placeholder is a dotted path
+ * resolved through the lookup the caller provides, or an expression over such
+ * paths (see `expression.algorithm`). No code is ever executed.
+ */
+import type { Lookup } from './value-text.algorithm.js';
+/**
+ * Whether a string contains at least one placeholder.
+ *
+ * @param text - The string.
+ * @returns `true` when it has a `{{ }}`.
+ */
+export declare function hasPlaceholder(text: string): boolean;
+/**
+ * Renders a template. When the template is exactly one placeholder the resolved
+ * value is returned as is (so a list or a number survives); otherwise every
+ * placeholder is stringified into the text, `undefined`/`null` as `''`.
+ *
+ * @param template - The string to render.
+ * @param lookup - Resolves a path.
+ * @returns The rendered value.
+ */
+export declare function render(template: string, lookup: Lookup): unknown;
+/**
+ * The value of one placeholder: a plain path is looked up as is; anything else
+ * is parsed and evaluated as an expression.
+ *
+ * @param inner - The trimmed text between the braces.
+ * @param lookup - Resolves a path.
+ * @returns The value.
+ * @throws Error when an expression does not parse.
+ */
+export declare function resolve(inner: string, lookup: Lookup): unknown;
+/**
+ * Renders every string inside a JSON-shaped value (an object, an array, or a
+ * string) with {@link render}, so a lone placeholder keeps its type
+ * (`"{{vars.limit}}"` becomes the number) and anything else becomes text.
+ * Numbers, booleans and `null` pass through untouched.
+ *
+ * @param value - The value.
+ * @param lookup - Resolves a path.
+ * @returns A new value with every string rendered.
+ */
+export declare function renderDeep(value: unknown, lookup: Lookup): unknown;
+/**
+ * Renders a template that must produce text.
+ *
+ * @param template - The string to render.
+ * @param lookup - Resolves a path.
+ * @returns The rendered text; a non-string single value is stringified.
+ */
+export declare function renderText(template: string, lookup: Lookup): string;
+//# sourceMappingURL=template.algorithm.d.ts.map

package/dist/template/value-path.algorithm.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Reads and writes values by dotted path (`seller.name`, `items.0.url`, `items[0].url`).
+ * Pure: the read never throws on a missing segment, the write creates what is missing.
+ */
+/**
+ * Splits a path into its segments; `a.b[0].c` and `a.b.0.c` are the same path.
+ *
+ * @param path - The dotted path.
+ * @returns Its segments, `[]` for an empty path or `.`.
+ */
+export declare function segmentsOf(path: string): string[];
+/**
+ * Reads a value by path. Only own properties are read, so `constructor`,
+ * `__proto__`, `toString` and the like resolve to `undefined` whatever the data.
+ *
+ * @param source - Where to read from.
+ * @param path - The dotted path; `.` or `''` returns the source itself.
+ * @returns The value, or `undefined` when any segment is missing.
+ */
+export declare function getPath(source: unknown, path: string): unknown;
+/**
+ * Writes a value by path, creating intermediate objects (or arrays for numeric segments).
+ *
+ * @param target - The object to write into. Mutated.
+ * @param path - The dotted path.
+ * @param value - The value to store.
+ */
+export declare function setPath(target: Record<string, unknown>, path: string, value: unknown): void;
+//# sourceMappingURL=value-path.algorithm.d.ts.map

package/dist/template/value-text.algorithm.d.ts

@@ -0,0 +1,18 @@
+/** How recipes read a value: as text for interpolation, as a truth for conditions. Shared by templates and expressions. */
+/** Resolves a dotted path to a value; `undefined` when unknown. */
+export type Lookup = (path: string) => unknown;
+/**
+ * Truthiness as recipes mean it: `when` and `until` conditions.
+ *
+ * @param value - Any rendered value.
+ * @returns `false` for `undefined`, `null`, `''`, `0`, `false`, `'false'`, `'0'`, `'null'` and an empty list.
+ */
+export declare function isTruthy(value: unknown): boolean;
+/**
+ * The text form of a value for interpolation.
+ *
+ * @param value - Any value.
+ * @returns A string; objects and arrays as JSON.
+ */
+export declare function stringify(value: unknown): string;
+//# sourceMappingURL=value-text.algorithm.d.ts.map