@fedify/uri-template 2.0.0-pr.475.1

package/dist/expand.d.ts

@@ -0,0 +1,72 @@
+import { TemplateAst } from "./ast.js";
+
+//#region src/expand.d.ts
+
+/**
+ * A scalar value that can be used in template expansion.
+ */
+type Scalar = string | number | boolean;
+/**
+ * A list of scalar values that can be used in template expansion.
+ */
+type List = (Scalar | undefined)[];
+/**
+ * A map-like object with scalar values.
+ */
+type MapLike = Record<string, Scalar | undefined>;
+/**
+ * Valid value types for template variables.
+ */
+type VarsValue = Scalar | List | MapLike | undefined;
+/**
+ * A collection of variables for template expansion.
+ * Maps variable names to their values.
+ *
+ * @example
+ * ```typescript
+ * const vars: Vars = {
+ *   var: "value",
+ *   list: ["red", "green", "blue"],
+ *   keys: { semi: ";", dot: ".", comma: "," }
+ * };
+ * ```
+ */
+type Vars = Record<string, VarsValue>;
+/**
+ * Expand a parsed template with variables according to RFC 6570 (Level 1-4).
+ *
+ * @param ast - The parsed template AST to expand
+ * @param vars - Variables to substitute into the template
+ * @returns The expanded URL string
+ *
+ * @remarks
+ * - Idempotent percent encoding (existing `%XX` kept)
+ * - Operator-specific empty/undefined rules:
+ *   - ";"  empty -> `nameOnly` (";x")
+ *   - "?" "&" empty -> "key=" ("?x=")
+ *   - `undefined` -> `omit` (all operators)
+ * - Label "." emits the dot even if empty ("X{.y}" with y="" -> "X.")
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { expand } from "./expand.ts";
+ *
+ * const ast = parse("{+x,hello,y}");
+ * const url = expand(ast, { x: "1024", hello: "Hello World!", y: "768" });
+ * // Returns: "1024,Hello%20World!,768"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { expand } from "./expand.ts";
+ *
+ * const ast = parse("{+path}/here");
+ * const url = expand(ast, { path: "/foo/bar" });
+ * // Returns: "/foo/bar/here"
+ * ```
+ */
+declare function expand(ast: TemplateAst, vars: Vars): string;
+//#endregion
+export { Vars, expand };

package/dist/expand.js

@@ -0,0 +1,94 @@
+import { OP, encodeComponentIdempotent } from "./spec.js";
+
+//#region src/expand.ts
+function emitNamed(spec, name, raw) {
+	return spec.named ? raw === "" && spec.ifEmpty === "empty" ? `${name}${spec.kvSep}` : `${name}${spec.kvSep}${raw}` : raw;
+}
+function expandVar(op, v, value) {
+	const spec = OP[op];
+	const enc = (str) => encodeComponentIdempotent(str, spec.allowReserved, spec.reservedSet);
+	if (value === void 0 || value === null) return [];
+	if (Array.isArray(value)) {
+		const items = value.filter((x) => x !== void 0).map((x) => enc(String(x)));
+		if (items.length === 0) {
+			if (spec.first === ".") return [""];
+			if (spec.named && spec.ifEmpty === "nameOnly") return [v.name];
+			if (spec.named && spec.ifEmpty === "empty") return [`${v.name}${spec.kvSep}`];
+			return [];
+		}
+		if (v.explode) return items.map((it) => emitNamed(spec, v.name, it));
+		return [emitNamed(spec, v.name, items.join(","))];
+	}
+	if (typeof value === "object" && value && !Array.isArray(value)) {
+		const entries = Object.entries(value).filter(([, vv]) => vv !== void 0);
+		if (entries.length === 0) {
+			if (spec.named && spec.ifEmpty === "nameOnly") return [v.name];
+			if (spec.named && spec.ifEmpty === "empty") return [`${v.name}${spec.kvSep}`];
+			return [];
+		}
+		if (v.explode) return entries.map(([k, vv]) => `${enc(k)}${spec.kvSep}${enc(String(vv))}`);
+		const joined = entries.map(([k, vv]) => `${enc(k)},${enc(String(vv))}`).join(",");
+		return [emitNamed(spec, v.name, joined)];
+	}
+	let s = String(value);
+	if (v.prefix !== void 0) s = s.slice(0, v.prefix);
+	const e = enc(s);
+	if (e.length === 0) {
+		if (spec.first === ".") return [""];
+		if (spec.named && spec.ifEmpty === "nameOnly") return [v.name];
+		if (spec.named && spec.ifEmpty === "empty") return [`${v.name}${spec.kvSep}`];
+		return [];
+	}
+	return [emitNamed(spec, v.name, e)];
+}
+/**
+* Expand a parsed template with variables according to RFC 6570 (Level 1-4).
+*
+* @param ast - The parsed template AST to expand
+* @param vars - Variables to substitute into the template
+* @returns The expanded URL string
+*
+* @remarks
+* - Idempotent percent encoding (existing `%XX` kept)
+* - Operator-specific empty/undefined rules:
+*   - ";"  empty -> `nameOnly` (";x")
+*   - "?" "&" empty -> "key=" ("?x=")
+*   - `undefined` -> `omit` (all operators)
+* - Label "." emits the dot even if empty ("X{.y}" with y="" -> "X.")
+*
+* @example
+* ```typescript
+* import { parse } from "./parser.ts";
+* import { expand } from "./expand.ts";
+*
+* const ast = parse("{+x,hello,y}");
+* const url = expand(ast, { x: "1024", hello: "Hello World!", y: "768" });
+* // Returns: "1024,Hello%20World!,768"
+* ```
+*
+* @example
+* ```typescript
+* import { parse } from "./parser.ts";
+* import { expand } from "./expand.ts";
+*
+* const ast = parse("{+path}/here");
+* const url = expand(ast, { path: "/foo/bar" });
+* // Returns: "/foo/bar/here"
+* ```
+*/
+function expand(ast, vars) {
+	let out = "";
+	for (const node of ast.nodes) if (node.kind === "literal") out += node.value;
+	else {
+		const spec = OP[node.op];
+		const pieces = [];
+		for (const v of node.vars) pieces.push(...expandVar(node.op, v, vars[v.name]));
+		if (pieces.length === 0) continue;
+		if (spec.first) out += spec.first;
+		out += pieces.join(spec.itemSep);
+	}
+	return out;
+}
+
+//#endregion
+export { expand };

package/dist/index.cjs

@@ -0,0 +1,9 @@
+const require_expand = require('./expand.cjs');
+const require_match = require('./match.cjs');
+const require_parser = require('./parser.cjs');
+const require_compile = require('./compile.cjs');
+
+exports.compile = require_compile.compile;
+exports.expand = require_expand.expand;
+exports.match = require_match.match;
+exports.parse = require_parser.parse;

package/dist/index.d.cts

@@ -0,0 +1,6 @@
+import { Expression, Literal, Node, Operator, TemplateAst, VarSpec } from "./ast.cjs";
+import { Vars, expand } from "./expand.cjs";
+import { EncodingPolicy, MatchOptions, match } from "./match.cjs";
+import { CompileOptions, CompiledTemplate, compile } from "./compile.cjs";
+import { parse } from "./parser.cjs";
+export { CompileOptions, CompiledTemplate, EncodingPolicy, Expression, Literal, MatchOptions, Node, Operator, TemplateAst, VarSpec, Vars, compile, expand, match, parse };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Expression, Literal, Node, Operator, TemplateAst, VarSpec } from "./ast.js";
+import { Vars, expand } from "./expand.js";
+import { EncodingPolicy, MatchOptions, match } from "./match.js";
+import { CompileOptions, CompiledTemplate, compile } from "./compile.js";
+import { parse } from "./parser.js";
+export { CompileOptions, CompiledTemplate, EncodingPolicy, Expression, Literal, MatchOptions, Node, Operator, TemplateAst, VarSpec, Vars, compile, expand, match, parse };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { expand } from "./expand.js";
+import { match } from "./match.js";
+import { parse } from "./parser.js";
+import { compile } from "./compile.js";
+
+export { compile, expand, match, parse };

package/dist/match.cjs

@@ -0,0 +1,180 @@
+const require_spec = require('./spec.cjs');
+
+//#region src/match.ts
+function decodeAccordingToPolicy(s, policy) {
+	if (policy === "opaque") return s;
+	if (policy === "cooked") return require_spec.strictPercentDecode(s);
+	return {
+		raw: s,
+		decoded: require_spec.strictPercentDecode(s)
+	};
+}
+/**
+* consume a percent triplet or a single char; used to advance safely
+*
+* Percent triplet handling policies:
+* - When advancing, treat "%XX" as a single atom to avoid slicing inside a byte.
+* - In strict mode, a bare '%' or bad hex after '%' fails the match.
+*/
+function advanceOne(url, i) {
+	if (i < url.length && url[i] === "%" && require_spec.looksLikePctTriplet(url, i)) return i + 3;
+	return i + 1;
+}
+/**
+* Match a URL string against a compiled template and extract variables.
+*
+* @param ast - The parsed template AST to match against
+* @param url - The URL string to match
+* @param opts - Optional matching options
+* @returns An object with extracted variables if matched, null otherwise
+*
+* Encoding policies:
+* - "opaque"  -> return raw percent-encoded slices (byte-for-byte round-trip)
+* - "cooked"  -> decode %XX exactly once
+* - "lossless"-> { raw, decoded } pair
+*
+* Strictness:
+* - strict=true rejects bad percent triplets (e.g. "%GZ"), preventing
+*   ambiguous or lossy normalization early.
+*
+* @example
+* ```typescript
+* import { parse } from "./parser.ts";
+* import { match } from "./match.ts";
+*
+* const ast = parse("/repos{/owner,repo}{?q,lang}");
+* const result = match(ast, "/repos/alice/hello%2Fworld?q=a%20b&lang=en", { encoding: "opaque" });
+* // Returns: { vars: { owner: "alice", repo: "hello%2Fworld", q: "a%20b", lang: "en" } }
+* ```
+*
+* @example
+* ```typescript
+* import { parse } from "./parser.ts";
+* import { match } from "./match.ts";
+*
+* const ast = parse("/files{/path}");
+* const result = match(ast, "/files/a%2Fb", { encoding: "cooked" });
+* // Returns: { vars: { path: "a/b" } }
+* ```
+*/
+function match(ast, url, opts) {
+	const policy = opts?.encoding ?? "opaque";
+	const strict = opts?.strict ?? true;
+	let i = 0;
+	const varsOut = {};
+	const readLiteral = (lit) => {
+		if (url.slice(i, i + lit.length) !== lit) return false;
+		i += lit.length;
+		return true;
+	};
+	const nextIs = (s) => url.slice(i, i + s.length) === s;
+	for (const node of ast.nodes) {
+		if (node.kind === "literal") {
+			if (!readLiteral(node.value)) return null;
+			continue;
+		}
+		const spec = require_spec.OP[node.op];
+		if (spec.first) {
+			if (!readLiteral(spec.first)) return null;
+		}
+		const takeUntil = (stopPred) => {
+			const start = i;
+			while (i < url.length && !stopPred(i)) {
+				if (strict && url[i] === "%" && !require_spec.looksLikePctTriplet(url, i)) return "";
+				i = advanceOne(url, i);
+			}
+			return url.slice(start, i);
+		};
+		const emitScalar = (v, raw) => {
+			varsOut[v.name] = decodeAccordingToPolicy(raw, policy);
+		};
+		const splitItems = (raw) => {
+			if (raw.length === 0) return [""];
+			const sep = spec.itemSep;
+			const out = [];
+			let start = 0;
+			for (let j = 0; j <= raw.length;) {
+				if (j === raw.length || raw.slice(j, j + sep.length) === sep) {
+					out.push(raw.slice(start, j));
+					j += sep.length;
+					start = j;
+					continue;
+				}
+				j = advanceOne(raw, j);
+			}
+			return out;
+		};
+		const captureOneVar = (v, last, nextLiteral) => {
+			const stopPred = (j) => {
+				if (nextLiteral && url.slice(j, j + nextLiteral.length) === nextLiteral) return true;
+				if (!last && spec.itemSep && url.slice(j, j + spec.itemSep.length) === spec.itemSep) return true;
+				return false;
+			};
+			const raw = takeUntil(stopPred);
+			if (raw === "" && strict && i < url.length && url[i] !== spec.itemSep && nextLiteral === null) return false;
+			if (v.explode) {
+				const parts = splitItems(raw);
+				if (spec.named) varsOut[v.name] = parseExplodeNamedParts(v, parts, spec, policy);
+				else varsOut[v.name] = parts.map((p) => decodeAccordingToPolicy(p, policy));
+			} else if (spec.named) {
+				const [ok, val] = captureNamedNonExplode(v, raw, spec, policy);
+				if (!ok) return false;
+				varsOut[v.name] = val;
+			} else emitScalar(v, raw);
+			if (!last && spec.itemSep && nextIs(spec.itemSep)) i += spec.itemSep.length;
+			return true;
+		};
+		for (let idx = 0; idx < node.vars.length; idx++) {
+			const v = node.vars[idx];
+			const last = idx === node.vars.length - 1;
+			let nextLiteral = null;
+			const nodeIndex = ast.nodes.indexOf(node);
+			for (let k = nodeIndex + 1; k < ast.nodes.length; k++) {
+				const n = ast.nodes[k];
+				if (n.kind === "literal" && n.value.length > 0) {
+					nextLiteral = n.value;
+					break;
+				}
+				if (n.kind === "expression" && require_spec.OP[n.op].first) {
+					nextLiteral = require_spec.OP[n.op].first;
+					break;
+				}
+			}
+			if (!captureOneVar(v, last, nextLiteral)) return null;
+		}
+	}
+	return { vars: varsOut };
+}
+function captureNamedNonExplode(v, raw, spec, policy) {
+	const eq = raw.indexOf(spec.kvSep);
+	if (eq === -1) {
+		if (spec.first === ";") {
+			if (raw === v.name) return [true, decodeAccordingToPolicy("", policy)];
+		}
+		return [false, null];
+	}
+	const lhs = raw.slice(0, eq), rhs = raw.slice(eq + spec.kvSep.length);
+	if (lhs !== v.name) return [false, null];
+	return [true, decodeAccordingToPolicy(rhs, policy)];
+}
+function parseExplodeNamedParts(v, parts, spec, policy) {
+	const allVarName = parts.every((p) => p.startsWith(v.name + spec.kvSep));
+	if (allVarName) return parts.map((p) => {
+		const rhs = p.slice((v.name + spec.kvSep).length);
+		return decodeAccordingToPolicy(rhs, policy);
+	});
+	const obj = {};
+	for (const p of parts) {
+		const i = p.indexOf(spec.kvSep);
+		if (i < 0) {
+			obj[decodeAccordingToPolicy(p, policy)] = "";
+			continue;
+		}
+		const k = p.slice(0, i), val = p.slice(i + spec.kvSep.length);
+		obj[decodeAccordingToPolicy(k, policy)] = decodeAccordingToPolicy(val, policy);
+	}
+	return obj;
+}
+
+//#endregion
+exports.match = match;

package/dist/match.d.cts

@@ -0,0 +1,92 @@
+import { TemplateAst } from "./ast.cjs";
+
+//#region src/match.d.ts
+
+/**
+ * Encoding policy for variable values when matching URLs.
+ *
+ * Three modes are supported:
+ * - `"opaque"` (default):
+ *   - Treats `%XX` as opaque atoms.
+ *   - No decoding is applied; raw bytes are preserved.
+ *   - Guarantees byte-for-byte symmetry:
+ *     `expand(match(url)) === url`.
+ *   - Background: added to solve `uri-template-router#11` where
+ *     sequences like "%30#" lost information.
+ *
+ * - `"cooked"`:
+ *   - Decodes valid `%XX` sequences exactly once.
+ *   - More convenient for application logic where you want
+ *     human-readable values (`"a%20b"` → `"a b"`).
+ *   - Guarantees semantic symmetry:
+ *     `match(expand(vars)) === vars`.
+ *   - Note: Name chosen to contrast with `"opaque"`: think of
+ *     “cooked strings” (escaped string literals) in programming languages.
+ *
+ * - `"lossless"`:
+ *   - Returns both raw and decoded forms:
+ *     `{ raw: "a%2Fb", decoded: "a/b" }`.
+ *   - Useful if you need to display the original URL while
+ *     still working with decoded values.
+ */
+type EncodingPolicy = "opaque" | "cooked" | "lossless";
+/**
+ * Options for matching URLs against templates.
+ *
+ * @remarks
+ * These options control how percent-encoded sequences are handled during matching.
+ */
+interface MatchOptions {
+  /**
+   * The encoding policy for variable values (default: "opaque").
+   */
+  encoding?: EncodingPolicy;
+  /**
+   * If true (default), malformed percent triplets cause matching to fail.
+   * If false, allows more lenient parsing but may lead to ambiguity.
+   */
+  strict?: boolean;
+}
+type VarsOut = Record<string, unknown>;
+/**
+ * Match a URL string against a compiled template and extract variables.
+ *
+ * @param ast - The parsed template AST to match against
+ * @param url - The URL string to match
+ * @param opts - Optional matching options
+ * @returns An object with extracted variables if matched, null otherwise
+ *
+ * Encoding policies:
+ * - "opaque"  -> return raw percent-encoded slices (byte-for-byte round-trip)
+ * - "cooked"  -> decode %XX exactly once
+ * - "lossless"-> { raw, decoded } pair
+ *
+ * Strictness:
+ * - strict=true rejects bad percent triplets (e.g. "%GZ"), preventing
+ *   ambiguous or lossy normalization early.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { match } from "./match.ts";
+ *
+ * const ast = parse("/repos{/owner,repo}{?q,lang}");
+ * const result = match(ast, "/repos/alice/hello%2Fworld?q=a%20b&lang=en", { encoding: "opaque" });
+ * // Returns: { vars: { owner: "alice", repo: "hello%2Fworld", q: "a%20b", lang: "en" } }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { match } from "./match.ts";
+ *
+ * const ast = parse("/files{/path}");
+ * const result = match(ast, "/files/a%2Fb", { encoding: "cooked" });
+ * // Returns: { vars: { path: "a/b" } }
+ * ```
+ */
+declare function match(ast: TemplateAst, url: string, opts?: MatchOptions): null | {
+  vars: VarsOut;
+};
+//#endregion
+export { EncodingPolicy, MatchOptions, match };

package/dist/match.d.ts

@@ -0,0 +1,92 @@
+import { TemplateAst } from "./ast.js";
+
+//#region src/match.d.ts
+
+/**
+ * Encoding policy for variable values when matching URLs.
+ *
+ * Three modes are supported:
+ * - `"opaque"` (default):
+ *   - Treats `%XX` as opaque atoms.
+ *   - No decoding is applied; raw bytes are preserved.
+ *   - Guarantees byte-for-byte symmetry:
+ *     `expand(match(url)) === url`.
+ *   - Background: added to solve `uri-template-router#11` where
+ *     sequences like "%30#" lost information.
+ *
+ * - `"cooked"`:
+ *   - Decodes valid `%XX` sequences exactly once.
+ *   - More convenient for application logic where you want
+ *     human-readable values (`"a%20b"` → `"a b"`).
+ *   - Guarantees semantic symmetry:
+ *     `match(expand(vars)) === vars`.
+ *   - Note: Name chosen to contrast with `"opaque"`: think of
+ *     “cooked strings” (escaped string literals) in programming languages.
+ *
+ * - `"lossless"`:
+ *   - Returns both raw and decoded forms:
+ *     `{ raw: "a%2Fb", decoded: "a/b" }`.
+ *   - Useful if you need to display the original URL while
+ *     still working with decoded values.
+ */
+type EncodingPolicy = "opaque" | "cooked" | "lossless";
+/**
+ * Options for matching URLs against templates.
+ *
+ * @remarks
+ * These options control how percent-encoded sequences are handled during matching.
+ */
+interface MatchOptions {
+  /**
+   * The encoding policy for variable values (default: "opaque").
+   */
+  encoding?: EncodingPolicy;
+  /**
+   * If true (default), malformed percent triplets cause matching to fail.
+   * If false, allows more lenient parsing but may lead to ambiguity.
+   */
+  strict?: boolean;
+}
+type VarsOut = Record<string, unknown>;
+/**
+ * Match a URL string against a compiled template and extract variables.
+ *
+ * @param ast - The parsed template AST to match against
+ * @param url - The URL string to match
+ * @param opts - Optional matching options
+ * @returns An object with extracted variables if matched, null otherwise
+ *
+ * Encoding policies:
+ * - "opaque"  -> return raw percent-encoded slices (byte-for-byte round-trip)
+ * - "cooked"  -> decode %XX exactly once
+ * - "lossless"-> { raw, decoded } pair
+ *
+ * Strictness:
+ * - strict=true rejects bad percent triplets (e.g. "%GZ"), preventing
+ *   ambiguous or lossy normalization early.
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { match } from "./match.ts";
+ *
+ * const ast = parse("/repos{/owner,repo}{?q,lang}");
+ * const result = match(ast, "/repos/alice/hello%2Fworld?q=a%20b&lang=en", { encoding: "opaque" });
+ * // Returns: { vars: { owner: "alice", repo: "hello%2Fworld", q: "a%20b", lang: "en" } }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { parse } from "./parser.ts";
+ * import { match } from "./match.ts";
+ *
+ * const ast = parse("/files{/path}");
+ * const result = match(ast, "/files/a%2Fb", { encoding: "cooked" });
+ * // Returns: { vars: { path: "a/b" } }
+ * ```
+ */
+declare function match(ast: TemplateAst, url: string, opts?: MatchOptions): null | {
+  vars: VarsOut;
+};
+//#endregion
+export { EncodingPolicy, MatchOptions, match };