@fedify/uri-template 2.0.0-pr.475.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024–2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+<!-- deno-fmt-ignore-file -->
+
+@fedify/uri-template: RFC 6570 URI Template implementation
+===========================================================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+This package provides [RFC 6570] fully compliant URI template expansion and
+pattern matching library.  Supports symmetric matching where
+`expand(match(url))` and `match(expand(vars))` behave predictably.
+
+[JSR]: https://jsr.io/@fedify/uri-template
+[JSR badge]: https://jsr.io/badges/@fedify/uri-template
+[npm]: https://www.npmjs.com/package/@fedify/uri-template
+[npm badge]: https://img.shields.io/npm/v/@fedify/uri-template?logo=npm
+[RFC 6570]: https://datatracker.ietf.org/doc/html/rfc6570
+
+
+Features
+--------
+
+ -  **Full RFC 6570 Level 4 support**: Handles all operators and modifiers
+    (explode `*`, prefix `:n`)
+ -  **Symmetric pattern matching**:
+     -  `opaque`: byte-for-byte exact round-trips
+     -  `cooked`: human-readable decoded values
+     -  `lossless`: preserves both raw and decoded forms
+ -  **Strict percent-encoding validation**: Prevents malformed sequences
+    (`%GZ`, etc.)
+ -  **Deterministic expansion**: Correctly handles undefined/empty values per
+    RFC rules
+
+
+Installation
+------------
+
+~~~~ sh
+deno add jsr:@fedify/uri-template  # Deno
+npm  add     @fedify/uri-template  # npm
+pnpm add     @fedify/uri-template  # pnpm
+yarn add     @fedify/uri-template  # Yarn
+bun  add     @fedify/uri-template  # Bun
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { compile } from "@fedify/uri-template";
+
+const tmpl = compile("/repos{/owner,repo}{?q,lang}");
+
+// Expansion
+const url = tmpl.expand({ owner: "foo", repo: "hello/world", q: "a b" });
+// => "/repos/foo/hello%2Fworld?q=a%20b"
+
+// Matching
+const result = tmpl.match("/repos/foo/hello%2Fworld?q=a%20b", {
+  encoding: "cooked"
+});
+// => { owner: "foo", repo: "hello/world", q: "a b" }
+~~~~
+
+**Matching options:**
+
+ -  `encoding`: `"opaque"` (default, preserves raw) | `"cooked"` (decoded) |
+    `"lossless"` (both)
+ -  `strict`: `true` (default, strict) | `false` (lenient parsing)
+
+
+Documentation
+-------------
+
+For detailed implementation details, see [*specification.md*].
+
+[*specification.md*]: ./docs/specification.md

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/ast.d.cts

@@ -0,0 +1,39 @@
+//#region src/ast.d.ts
+/**
+ * RFC 6570 operator set. Keep in sync with {@link OperatorSpec} in spec.ts.
+ * The operator controls separators, first-char prefix, and reserved char handling.
+ */
+type Operator = "" | "+" | "#" | "." | "/" | ";" | "?" | "&";
+/**
+ * A variable specification inside an expression
+ * - `explode` (`*`) and `prefix` (`:n`) modifies are Level 4 features.
+ * - Parser guarantees: if `prefix` is present, it is a positive integer.
+ */
+interface VarSpec {
+  name: string;
+  explode: boolean;
+  prefix?: number;
+}
+type Node = Literal | Expression;
+interface Literal {
+  kind: "literal";
+  value: string;
+  start?: number;
+  end?: number;
+}
+interface Expression {
+  kind: "expression";
+  op: Operator;
+  vars: VarSpec[];
+  start?: number;
+  end?: number;
+}
+/**
+ * Template AST root. Expansion and matching both consume this structure.
+ * @note Literals are kept as-is to avoid re-encoding surprises.
+ */
+interface TemplateAst {
+  nodes: Node[];
+}
+//#endregion
+export { Expression, Literal, Node, Operator, TemplateAst, VarSpec };

package/dist/ast.d.ts

@@ -0,0 +1,39 @@
+//#region src/ast.d.ts
+/**
+ * RFC 6570 operator set. Keep in sync with {@link OperatorSpec} in spec.ts.
+ * The operator controls separators, first-char prefix, and reserved char handling.
+ */
+type Operator = "" | "+" | "#" | "." | "/" | ";" | "?" | "&";
+/**
+ * A variable specification inside an expression
+ * - `explode` (`*`) and `prefix` (`:n`) modifies are Level 4 features.
+ * - Parser guarantees: if `prefix` is present, it is a positive integer.
+ */
+interface VarSpec {
+  name: string;
+  explode: boolean;
+  prefix?: number;
+}
+type Node = Literal | Expression;
+interface Literal {
+  kind: "literal";
+  value: string;
+  start?: number;
+  end?: number;
+}
+interface Expression {
+  kind: "expression";
+  op: Operator;
+  vars: VarSpec[];
+  start?: number;
+  end?: number;
+}
+/**
+ * Template AST root. Expansion and matching both consume this structure.
+ * @note Literals are kept as-is to avoid re-encoding surprises.
+ */
+interface TemplateAst {
+  nodes: Node[];
+}
+//#endregion
+export { Expression, Literal, Node, Operator, TemplateAst, VarSpec };

package/dist/compile.cjs

@@ -0,0 +1,30 @@
+const require_expand = require('./expand.cjs');
+const require_match = require('./match.cjs');
+const require_parser = require('./parser.cjs');
+
+//#region src/compile.ts
+/**
+* Compile a template string once.
+* Returns a handle with:
+*  - `ast()`     -> the parsed AST (for diagnostics/introspection)
+*  - `expand()`  -> RFC 6570 expansion (L1–L4)
+*  - `match()`   -> symmetric pattern matching
+*
+* Rationale:
+* Compilation isolates parsing cost and allows future VM/bytecode backends
+* to optimize hot routes without changing the API.
+*/
+function compile(template) {
+	const ast = require_parser.parse(template);
+	return {
+		ast: () => ast,
+		expand: (vars) => require_expand.expand(ast, vars),
+		match: (url, mo) => {
+			const result = require_match.match(ast, url, mo);
+			return result ? { vars: result.vars } : null;
+		}
+	};
+}
+
+//#endregion
+exports.compile = compile;

package/dist/compile.d.cts

@@ -0,0 +1,80 @@
+import { TemplateAst } from "./ast.cjs";
+import { Vars } from "./expand.cjs";
+import { EncodingPolicy, MatchOptions } from "./match.cjs";
+
+//#region src/compile.d.ts
+
+/**
+ * Options that control how a compiled template behaves during matching.
+ *
+ * ### encoding
+ * Determines how percent-encoded sequences are handled.
+ *
+ * ### strict
+ * If true (default), malformed percent triplets (e.g. "%GZ" or lone "%")
+ * cause matching to fail immediately.
+ * Disabling strict mode may allow more lenient parsing but can lead to ambiguity.
+ */
+interface CompileOptions {
+  encoding?: EncodingPolicy;
+  strict?: boolean;
+}
+/**
+ * A compiled URI template that can efficiently expand and match URLs.
+ *
+ * @typeParam V - The type of variables expected by this template
+ *
+ * @example
+ * ```typescript
+ * const t = compile("{+path}/here");
+ * const url = t.expand({ path: "/foo/bar" }); // "/foo/bar/here"
+ * const match = t.match("/foo/bar/here"); // { vars: { path: "/foo/bar" } }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const t = compile("/repos{/owner,repo}{?q,lang}");
+ * const url = t.expand({ owner: "alice", repo: "hello/world", q: "a b", lang: "en" });
+ * // "/repos/alice/hello%2Fworld?q=a%20b&lang=en"
+ * ```
+ */
+interface CompiledTemplate<V = Record<string, unknown>> {
+  /**
+   * Get the parsed AST of this template.
+   * Useful for diagnostics and introspection.
+   *
+   * @returns The parsed template AST
+   */
+  ast(): TemplateAst;
+  /**
+   * Expand the template with the given variables according to RFC 6570.
+   *
+   * @param vars - Variables to substitute into the template
+   * @returns The expanded URL string
+   */
+  expand(vars: V & Vars): string;
+  /**
+   * Match a URL against this template and extract variables.
+   *
+   * @param url - The URL to match against the template
+   * @param opts - Optional matching options
+   * @returns An object with extracted variables if matched, null otherwise
+   */
+  match(url: string, opts?: MatchOptions): null | {
+    vars: V;
+  };
+}
+/**
+ * Compile a template string once.
+ * Returns a handle with:
+ *  - `ast()`     -> the parsed AST (for diagnostics/introspection)
+ *  - `expand()`  -> RFC 6570 expansion (L1–L4)
+ *  - `match()`   -> symmetric pattern matching
+ *
+ * Rationale:
+ * Compilation isolates parsing cost and allows future VM/bytecode backends
+ * to optimize hot routes without changing the API.
+ */
+declare function compile<V = Record<string, unknown>>(template: string): CompiledTemplate<V>;
+//#endregion
+export { CompileOptions, CompiledTemplate, compile };

package/dist/compile.d.ts

@@ -0,0 +1,80 @@
+import { TemplateAst } from "./ast.js";
+import { Vars } from "./expand.js";
+import { EncodingPolicy, MatchOptions } from "./match.js";
+
+//#region src/compile.d.ts
+
+/**
+ * Options that control how a compiled template behaves during matching.
+ *
+ * ### encoding
+ * Determines how percent-encoded sequences are handled.
+ *
+ * ### strict
+ * If true (default), malformed percent triplets (e.g. "%GZ" or lone "%")
+ * cause matching to fail immediately.
+ * Disabling strict mode may allow more lenient parsing but can lead to ambiguity.
+ */
+interface CompileOptions {
+  encoding?: EncodingPolicy;
+  strict?: boolean;
+}
+/**
+ * A compiled URI template that can efficiently expand and match URLs.
+ *
+ * @typeParam V - The type of variables expected by this template
+ *
+ * @example
+ * ```typescript
+ * const t = compile("{+path}/here");
+ * const url = t.expand({ path: "/foo/bar" }); // "/foo/bar/here"
+ * const match = t.match("/foo/bar/here"); // { vars: { path: "/foo/bar" } }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const t = compile("/repos{/owner,repo}{?q,lang}");
+ * const url = t.expand({ owner: "alice", repo: "hello/world", q: "a b", lang: "en" });
+ * // "/repos/alice/hello%2Fworld?q=a%20b&lang=en"
+ * ```
+ */
+interface CompiledTemplate<V = Record<string, unknown>> {
+  /**
+   * Get the parsed AST of this template.
+   * Useful for diagnostics and introspection.
+   *
+   * @returns The parsed template AST
+   */
+  ast(): TemplateAst;
+  /**
+   * Expand the template with the given variables according to RFC 6570.
+   *
+   * @param vars - Variables to substitute into the template
+   * @returns The expanded URL string
+   */
+  expand(vars: V & Vars): string;
+  /**
+   * Match a URL against this template and extract variables.
+   *
+   * @param url - The URL to match against the template
+   * @param opts - Optional matching options
+   * @returns An object with extracted variables if matched, null otherwise
+   */
+  match(url: string, opts?: MatchOptions): null | {
+    vars: V;
+  };
+}
+/**
+ * Compile a template string once.
+ * Returns a handle with:
+ *  - `ast()`     -> the parsed AST (for diagnostics/introspection)
+ *  - `expand()`  -> RFC 6570 expansion (L1–L4)
+ *  - `match()`   -> symmetric pattern matching
+ *
+ * Rationale:
+ * Compilation isolates parsing cost and allows future VM/bytecode backends
+ * to optimize hot routes without changing the API.
+ */
+declare function compile<V = Record<string, unknown>>(template: string): CompiledTemplate<V>;
+//#endregion
+export { CompileOptions, CompiledTemplate, compile };

package/dist/compile.js

@@ -0,0 +1,30 @@
+import { expand } from "./expand.js";
+import { match } from "./match.js";
+import { parse } from "./parser.js";
+
+//#region src/compile.ts
+/**
+* Compile a template string once.
+* Returns a handle with:
+*  - `ast()`     -> the parsed AST (for diagnostics/introspection)
+*  - `expand()`  -> RFC 6570 expansion (L1–L4)
+*  - `match()`   -> symmetric pattern matching
+*
+* Rationale:
+* Compilation isolates parsing cost and allows future VM/bytecode backends
+* to optimize hot routes without changing the API.
+*/
+function compile(template) {
+	const ast = parse(template);
+	return {
+		ast: () => ast,
+		expand: (vars) => expand(ast, vars),
+		match: (url, mo) => {
+			const result = match(ast, url, mo);
+			return result ? { vars: result.vars } : null;
+		}
+	};
+}
+
+//#endregion
+export { compile };

package/dist/error.cjs

@@ -0,0 +1,29 @@
+
+//#region src/error.ts
+/**
+* Error thrown when parsing an invalid RFC 6570 URI template.
+*/
+var ParseError = class ParseError extends Error {
+	/**
+	* The error name, always "RFC6570ParseError".
+	*/
+	name = "RFC6570ParseError";
+	/**
+	* The index in the template string where the error occurred.
+	*/
+	index;
+	/**
+	* Create a new ParseError.
+	*
+	* @param message - The error message
+	* @param index - The index in the template string where the error occurred
+	*/
+	constructor(message, index) {
+		super(message);
+		this.index = index;
+		Object.setPrototypeOf(this, ParseError.prototype);
+	}
+};
+
+//#endregion
+exports.ParseError = ParseError;

package/dist/error.js

@@ -0,0 +1,28 @@
+//#region src/error.ts
+/**
+* Error thrown when parsing an invalid RFC 6570 URI template.
+*/
+var ParseError = class ParseError extends Error {
+	/**
+	* The error name, always "RFC6570ParseError".
+	*/
+	name = "RFC6570ParseError";
+	/**
+	* The index in the template string where the error occurred.
+	*/
+	index;
+	/**
+	* Create a new ParseError.
+	*
+	* @param message - The error message
+	* @param index - The index in the template string where the error occurred
+	*/
+	constructor(message, index) {
+		super(message);
+		this.index = index;
+		Object.setPrototypeOf(this, ParseError.prototype);
+	}
+};
+
+//#endregion
+export { ParseError };

package/dist/expand.cjs

@@ -0,0 +1,94 @@
+const require_spec = require('./spec.cjs');
+
+//#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 = require_spec.OP[op];
+	const enc = (str) => require_spec.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 = require_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
+exports.expand = expand;

package/dist/expand.d.cts

@@ -0,0 +1,72 @@
+import { TemplateAst } from "./ast.cjs";
+
+//#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 };