@fedify/uri-template 2.0.0-pr.475.1

package/dist/rfc6570.spec.js

@@ -0,0 +1,418 @@
+import { compile } from "./compile.js";
+import { deepStrictEqual } from "node:assert/strict";
+import { describe, test } from "node:test";
+
+//#region src/rfc6570.spec.ts
+describe("basic expansion", () => {
+	test("scalar", () => {
+		const t = compile("{var}");
+		deepStrictEqual(t.expand({ var: "value" }), "value");
+		deepStrictEqual(t.expand({ var: "va lue" }), "va%20lue");
+		deepStrictEqual(t.expand({ var: "100%" }), "100%25");
+	});
+	test("list (no explode)", () => {
+		const t = compile("{list}");
+		deepStrictEqual(t.expand({ list: [
+			"red",
+			"green",
+			"blue"
+		] }), "red,green,blue");
+	});
+	test("map (no explode)", () => {
+		const t = compile("{keys}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "semi,%3B,dot,.,comma,%2C");
+	});
+	test("multiple vars", () => {
+		const t = compile("{x,y}");
+		deepStrictEqual(t.expand({ x: "1024" }), "1024");
+	});
+});
+describe("{+var} reserved expansion", () => {
+	test("{+var} allows reserved - basic", () => {
+		const t = compile("{+var}");
+		deepStrictEqual(t.expand({ var: "value" }), "value");
+	});
+	test("{+var} allows reserved - percent encoding", () => {
+		const t = compile("{+hello}");
+		deepStrictEqual(t.expand({ hello: "Hello World!" }), "Hello%20World!");
+	});
+	test("{+var} allows reserved - already encoded", () => {
+		const t = compile("{+half}");
+		deepStrictEqual(t.expand({ half: "50%" }), "50%25");
+	});
+	test("{+var} allows reserved - base URL comparison", () => {
+		const t1 = compile("{base}index");
+		const t2 = compile("{+base}index");
+		const vars = { base: "http://example.com/home/" };
+		deepStrictEqual(t1.expand(vars), "http%3A%2F%2Fexample.com%2Fhome%2Findex");
+		deepStrictEqual(t2.expand(vars), "http://example.com/home/index");
+	});
+	test("{+var} allows reserved - empty value", () => {
+		const t = compile("O{+empty}X");
+		deepStrictEqual(t.expand({ empty: "" }), "OX");
+	});
+	test("{+var} allows reserved - undefined value", () => {
+		const t = compile("O{+undef}X");
+		deepStrictEqual(t.expand({ undef: void 0 }), "OX");
+	});
+	test("{+var} allows reserved - path", () => {
+		const t = compile("{+path}");
+		deepStrictEqual(t.expand({ path: "/foo/bar" }), "/foo/bar");
+	});
+	test("{+var} allows reserved - path appended", () => {
+		const t = compile("{+path}/here");
+		deepStrictEqual(t.expand({ path: "/foo/bar" }), "/foo/bar/here");
+	});
+	test("{+var} allows reserved - in query", () => {
+		const t = compile("here?ref={+path}");
+		deepStrictEqual(t.expand({ path: "/foo/bar" }), "here?ref=/foo/bar");
+	});
+	test("{+var} allows reserved - mixed with normal var", () => {
+		const t = compile("up{+path}{var}/here");
+		deepStrictEqual(t.expand({
+			path: "/foo/bar",
+			var: "value"
+		}), "up/foo/barvalue/here");
+	});
+	test("{+var} allows reserved - multiple vars", () => {
+		const t = compile("{+x,hello,y}");
+		deepStrictEqual(t.expand({
+			x: "1024",
+			hello: "Hello World!",
+			y: "768"
+		}), "1024,Hello%20World!,768");
+	});
+	test("{+var} allows reserved - multiple vars with path", () => {
+		const t = compile("{+path,x}/here");
+		deepStrictEqual(t.expand({
+			path: "/foo/bar",
+			x: "1024"
+		}), "/foo/bar,1024/here");
+	});
+	test("{+var} allows reserved - prefix modifier", () => {
+		const t = compile("{+path:6}/here");
+		deepStrictEqual(t.expand({ path: "/foo/bar" }), "/foo/b/here");
+	});
+	test("{+var} allows reserved - list", () => {
+		const t = compile("{+list}");
+		deepStrictEqual(t.expand({ list: [
+			"red",
+			"green",
+			"blue"
+		] }), "red,green,blue");
+	});
+	test("{+var} allows reserved - list explode", () => {
+		const t = compile("{+list*}");
+		deepStrictEqual(t.expand({ list: [
+			"red",
+			"green",
+			"blue"
+		] }), "red,green,blue");
+	});
+	test("{+var} allows reserved - map", () => {
+		const t = compile("{+keys}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "semi,;,dot,.,comma,,");
+	});
+	test("{+var} allows reserved - map explode", () => {
+		const t = compile("{+keys*}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "semi=;,dot=.,comma=,");
+	});
+});
+describe("{#var} fragment expansion", () => {
+	test("{#var} fragment", () => {
+		const t = compile("{#frag}");
+		deepStrictEqual(t.expand({ frag: "a b" }), "#a%20b");
+		deepStrictEqual(t.expand({ frag: "a/b?c#d" }), "#a/b?c%23d");
+	});
+});
+describe("{.var} label expansion", () => {
+	test("{.var} label - basic", () => {
+		const t = compile("www{.domain}");
+		deepStrictEqual(t.expand({ domain: "example" }), "www.example");
+	});
+	test("{.var} label - single variable", () => {
+		const t = compile("{.who}");
+		deepStrictEqual(t.expand({ who: "fred" }), ".fred");
+	});
+	test("{.var} label - same variable twice", () => {
+		const t = compile("{.who,who}");
+		deepStrictEqual(t.expand({ who: "fred" }), ".fred.fred");
+	});
+	test("{.var} label - mixed variables with encoding", () => {
+		const t = compile("{.half,who}");
+		deepStrictEqual(t.expand({
+			half: "50%",
+			who: "fred"
+		}), ".50%25.fred");
+	});
+	test("{.var} label - explode with multiple labels", () => {
+		const t = compile("www{.dom*}");
+		deepStrictEqual(t.expand({ dom: ["example", "com"] }), "www.example.com");
+	});
+	test("{.var} label - with prefix", () => {
+		const t = compile("X{.var}");
+		deepStrictEqual(t.expand({ var: "value" }), "X.value");
+	});
+	test("{.var} label - empty value", () => {
+		const t = compile("X{.empty}");
+		deepStrictEqual(t.expand({ empty: "" }), "X.");
+	});
+	test("{.var} label - undefined value", () => {
+		const t = compile("X{.undef}");
+		deepStrictEqual(t.expand({ undef: void 0 }), "X");
+	});
+	test("{.var} label - prefix modifier", () => {
+		const t = compile("X{.var:3}");
+		deepStrictEqual(t.expand({ var: "value" }), "X.val");
+	});
+	test("{.var} label - list without explode", () => {
+		const t = compile("X{.list}");
+		deepStrictEqual(t.expand({ list: [
+			"red",
+			"green",
+			"blue"
+		] }), "X.red,green,blue");
+	});
+	test("{.var} label - list with explode", () => {
+		const t = compile("X{.list*}");
+		deepStrictEqual(t.expand({ list: [
+			"red",
+			"green",
+			"blue"
+		] }), "X.red.green.blue");
+	});
+	test("{.var} label - map without explode", () => {
+		const t = compile("X{.keys}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "X.semi,%3B,dot,.,comma,%2C");
+	});
+	test("{.var} label - map with explode", () => {
+		const t = compile("X{.keys*}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "X.semi=%3B.dot=..comma=%2C");
+	});
+	test("{.var} label - empty map without explode", () => {
+		const t = compile("X{.empty_keys}");
+		deepStrictEqual(t.expand({ empty_keys: {} }), "X");
+	});
+	test("{.var} label - empty map with explode", () => {
+		const t = compile("X{.empty_keys*}");
+		deepStrictEqual(t.expand({ empty_keys: {} }), "X");
+	});
+});
+describe("path and query operators", () => {
+	test("{/var} path segment", () => {
+		const t = compile("/users{/id}");
+		deepStrictEqual(t.expand({ id: "a/b" }), "/users/a%2Fb");
+	});
+	test("{;x,y} matrix params", () => {
+		const t = compile("/res{;x,y}");
+		deepStrictEqual(t.expand({
+			x: "a b",
+			y: ""
+		}), "/res;x=a%20b;y");
+		deepStrictEqual(t.expand({
+			x: void 0,
+			y: void 0
+		}), "/res");
+	});
+	test("{?x,y} query", () => {
+		const t = compile("/search{?q,lang}");
+		deepStrictEqual(t.expand({
+			q: "a b",
+			lang: "en"
+		}), "/search?q=a%20b&lang=en");
+		deepStrictEqual(t.expand({
+			q: "",
+			lang: void 0
+		}), "/search?q=");
+	});
+	test("{&x,y} query continuation", () => {
+		const t = compile("/search?q=init{&x,y}");
+		deepStrictEqual(t.expand({
+			x: "1",
+			y: "2"
+		}), "/search?q=init&x=1&y=2");
+	});
+});
+describe("explode modifier", () => {
+	test("explode list", () => {
+		const t = compile("/tags{;tags*}");
+		deepStrictEqual(t.expand({ tags: [
+			"red",
+			"green",
+			"blue"
+		] }), "/tags;tags=red;tags=green;tags=blue");
+	});
+	test("explode map", () => {
+		const t = compile("{?keys*}");
+		deepStrictEqual(t.expand({ keys: {
+			semi: ";",
+			dot: ".",
+			comma: ","
+		} }), "?semi=%3B&dot=.&comma=%2C");
+	});
+});
+describe("prefix modifier", () => {
+	test("prefix :n with scalar", () => {
+		const t = compile("{var:3}");
+		deepStrictEqual(t.expand({ var: "abcdef" }), "abc");
+	});
+	test("prefix with reserved content", () => {
+		const t = compile("/cut/{x:5}");
+		deepStrictEqual(t.expand({ x: "abc/def?ghi" }), "/cut/abc%2Fd");
+	});
+});
+describe("round-trip tests", () => {
+	test("expand(match(url)) === url (opaque)", () => {
+		const t = compile("/repos{/owner,repo}{?q,lang}");
+		const url = t.expand({
+			owner: "alice",
+			repo: "hello/world",
+			q: "a b",
+			lang: "en"
+		});
+		const m = t.match(url, { encoding: "opaque" });
+		deepStrictEqual(m !== null, true);
+		const url2 = t.expand(m.vars);
+		deepStrictEqual(url2, url);
+	});
+	test("match(expand(vars)) ≅ vars (cooked)", () => {
+		const t = compile("/u{/id}{?q}");
+		const vars = {
+			id: "a/b",
+			q: "x y"
+		};
+		const url = t.expand(vars);
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m !== null, true);
+		deepStrictEqual(m.vars, vars);
+	});
+	test("explode list stays list in cooked", () => {
+		const t = compile("/t{;tags*}");
+		const url = t.expand({ tags: ["a b", "c"] });
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m !== null, true);
+		deepStrictEqual(m.vars.tags, ["a b", "c"]);
+	});
+	test("explode map stays map in cooked", () => {
+		const t = compile("{?m*}");
+		const url = t.expand({ m: {
+			a: "1 2",
+			b: "/"
+		} });
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m !== null, true);
+		deepStrictEqual(m.vars.m, {
+			a: "1 2",
+			b: "/"
+		});
+	});
+});
+describe("encoding and special cases", () => {
+	/**
+	* Regression for https://github.com/awwright/uri-template-router/issues/11:
+	* Ensure that percent-encoded sequences and '#' handling do not lose information.
+	*/
+	test("opaque preserves raw percent sequences", () => {
+		const t = compile("{#frag}");
+		const url = t.expand({ frag: "%30#" });
+		const mOpaque = t.match(url, { encoding: "opaque" });
+		deepStrictEqual(mOpaque !== null, true);
+		deepStrictEqual(mOpaque.vars.frag, mOpaque.vars.frag);
+		const mCooked = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(mCooked !== null, true);
+		deepStrictEqual(typeof mCooked.vars.frag, "string");
+		deepStrictEqual(mCooked.vars.frag.includes("#"), true);
+	});
+	test("bad percent triplet during match => null (strict default)", () => {
+		const t = compile("/x{/id}");
+		const m = t.match("/x/%GZ", { encoding: "opaque" });
+		deepStrictEqual(m, null);
+	});
+	test("idempotent expand: do not double-encode existing %XX", () => {
+		const t = compile("/p{/x}");
+		const url = t.expand({ x: "a%2Fb" });
+		deepStrictEqual(url, "/p/a%2Fb");
+	});
+	test("space encoding", () => {
+		const t = compile("/s{/x}{?q}");
+		const url = t.expand({
+			x: "a b",
+			q: "x y"
+		});
+		deepStrictEqual(url, "/s/a%20b?q=x%20y");
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m.vars.x, "a b");
+		deepStrictEqual(m.vars.q, "x y");
+	});
+	test("greedy capture until next literal", () => {
+		const t = compile("/r{?q}#end");
+		const url = t.expand({ q: "a,b,c" });
+		deepStrictEqual(url, "/r?q=a%2Cb%2Cc#end");
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m !== null, true);
+		deepStrictEqual(m.vars.q, "a,b,c");
+	});
+	test("multiple expressions with separators", () => {
+		const t = compile("/x{/a}{/b}{?c}{&d}");
+		const url = t.expand({
+			a: "1",
+			b: "2/3",
+			c: "4 5",
+			d: "6"
+		});
+		deepStrictEqual(url, "/x/1/2%2F3?c=4%205&d=6");
+		const m = t.match(url, { encoding: "cooked" });
+		deepStrictEqual(m.vars, {
+			a: "1",
+			b: "2/3",
+			c: "4 5",
+			d: "6"
+		});
+	});
+});
+describe("undefined and empty value handling", () => {
+	test("undefined omits in simple operator", () => {
+		const t = compile("A{var}Z");
+		deepStrictEqual(t.expand({ var: void 0 }), "AZ");
+	});
+	test("empty string is nameOnly in ';' operator", () => {
+		const t = compile("{;x}");
+		deepStrictEqual(t.expand({ x: "" }), ";x");
+		deepStrictEqual(t.expand({ x: void 0 }), "");
+	});
+	test("undefined query param omitted", () => {
+		const t = compile("/s{?q,lang}");
+		deepStrictEqual(t.expand({
+			q: void 0,
+			lang: "en"
+		}), "/s?lang=en");
+	});
+	test("match allows empty value", () => {
+		const t = compile("/s{?q}");
+		const m = t.match("/s?q=", { encoding: "opaque" });
+		deepStrictEqual(m !== null, true);
+		deepStrictEqual(m.vars.q, "");
+	});
+});
+
+//#endregion

package/dist/spec.cjs

@@ -0,0 +1,112 @@
+
+//#region src/spec.ts
+const UNRESERVED = new Set([..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~"]);
+const GEN_DELIMS = ":/?#[]@";
+const SUB_DELIMS = "!$&'()*+,;=";
+const RESERVED_GENERAL = new Set([...GEN_DELIMS + SUB_DELIMS]);
+const RESERVED_NO_HASH = new Set([...":/?[]@" + SUB_DELIMS + "?"]);
+function looksLikePctTriplet(s, i) {
+	if (s[i] !== "%" || i + 2 >= s.length) return false;
+	const a = s[i + 1], b = s[i + 2];
+	const hex = (c) => "0" <= c && c <= "9" || "a" <= c && c <= "f" || "A" <= c && c <= "F";
+	return hex(a) && hex(b);
+}
+const OP = {
+	"": {
+		allowReserved: false,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"+": {
+		allowReserved: true,
+		reservedSet: RESERVED_GENERAL,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"#": {
+		first: "#",
+		allowReserved: true,
+		reservedSet: RESERVED_NO_HASH,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	".": {
+		first: ".",
+		allowReserved: false,
+		itemSep: ".",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"/": {
+		first: "/",
+		allowReserved: false,
+		itemSep: "/",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	";": {
+		first: ";",
+		named: true,
+		allowReserved: false,
+		itemSep: ";",
+		kvSep: "=",
+		ifEmpty: "nameOnly"
+	},
+	"?": {
+		first: "?",
+		named: true,
+		allowReserved: false,
+		itemSep: "&",
+		kvSep: "=",
+		ifEmpty: "empty"
+	},
+	"&": {
+		first: "&",
+		named: true,
+		allowReserved: false,
+		itemSep: "&",
+		kvSep: "=",
+		ifEmpty: "empty"
+	}
+};
+function encodeComponentIdempotent(s, allowReserved, reservedSet) {
+	let out = "";
+	for (let i = 0; i < s.length;) {
+		if (s[i] === "%" && looksLikePctTriplet(s, i)) {
+			out += s.slice(i, i + 3);
+			i += 3;
+			continue;
+		}
+		const ch = s[i];
+		if (UNRESERVED.has(ch)) {
+			out += ch;
+			i++;
+			continue;
+		}
+		if (allowReserved && reservedSet?.has(ch)) {
+			out += ch;
+			i++;
+			continue;
+		}
+		const bytes = new TextEncoder().encode(ch);
+		for (const b of bytes) out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+		i++;
+	}
+	return out;
+}
+function strictPercentDecode(s) {
+	for (let i = 0; i < s.length;) if (s[i] === "%") {
+		if (!looksLikePctTriplet(s, i)) throw new Error("Bad percent sequence");
+		i += 3;
+	} else i++;
+	return decodeURIComponent(s);
+}
+
+//#endregion
+exports.OP = OP;
+exports.encodeComponentIdempotent = encodeComponentIdempotent;
+exports.looksLikePctTriplet = looksLikePctTriplet;
+exports.strictPercentDecode = strictPercentDecode;

package/dist/spec.js

@@ -0,0 +1,108 @@
+//#region src/spec.ts
+const UNRESERVED = new Set([..."abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~"]);
+const GEN_DELIMS = ":/?#[]@";
+const SUB_DELIMS = "!$&'()*+,;=";
+const RESERVED_GENERAL = new Set([...GEN_DELIMS + SUB_DELIMS]);
+const RESERVED_NO_HASH = new Set([...":/?[]@" + SUB_DELIMS + "?"]);
+function looksLikePctTriplet(s, i) {
+	if (s[i] !== "%" || i + 2 >= s.length) return false;
+	const a = s[i + 1], b = s[i + 2];
+	const hex = (c) => "0" <= c && c <= "9" || "a" <= c && c <= "f" || "A" <= c && c <= "F";
+	return hex(a) && hex(b);
+}
+const OP = {
+	"": {
+		allowReserved: false,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"+": {
+		allowReserved: true,
+		reservedSet: RESERVED_GENERAL,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"#": {
+		first: "#",
+		allowReserved: true,
+		reservedSet: RESERVED_NO_HASH,
+		itemSep: ",",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	".": {
+		first: ".",
+		allowReserved: false,
+		itemSep: ".",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	"/": {
+		first: "/",
+		allowReserved: false,
+		itemSep: "/",
+		kvSep: "=",
+		ifEmpty: "omit"
+	},
+	";": {
+		first: ";",
+		named: true,
+		allowReserved: false,
+		itemSep: ";",
+		kvSep: "=",
+		ifEmpty: "nameOnly"
+	},
+	"?": {
+		first: "?",
+		named: true,
+		allowReserved: false,
+		itemSep: "&",
+		kvSep: "=",
+		ifEmpty: "empty"
+	},
+	"&": {
+		first: "&",
+		named: true,
+		allowReserved: false,
+		itemSep: "&",
+		kvSep: "=",
+		ifEmpty: "empty"
+	}
+};
+function encodeComponentIdempotent(s, allowReserved, reservedSet) {
+	let out = "";
+	for (let i = 0; i < s.length;) {
+		if (s[i] === "%" && looksLikePctTriplet(s, i)) {
+			out += s.slice(i, i + 3);
+			i += 3;
+			continue;
+		}
+		const ch = s[i];
+		if (UNRESERVED.has(ch)) {
+			out += ch;
+			i++;
+			continue;
+		}
+		if (allowReserved && reservedSet?.has(ch)) {
+			out += ch;
+			i++;
+			continue;
+		}
+		const bytes = new TextEncoder().encode(ch);
+		for (const b of bytes) out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+		i++;
+	}
+	return out;
+}
+function strictPercentDecode(s) {
+	for (let i = 0; i < s.length;) if (s[i] === "%") {
+		if (!looksLikePctTriplet(s, i)) throw new Error("Bad percent sequence");
+		i += 3;
+	} else i++;
+	return decodeURIComponent(s);
+}
+
+//#endregion
+export { OP, encodeComponentIdempotent, looksLikePctTriplet, strictPercentDecode };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@fedify/uri-template",
+  "version": "2.0.0-pr.475.1",
+  "description": "URI Template (RFC 6570) utilities for Fedify",
+  "keywords": [
+    "Fedify",
+    "URI",
+    "template",
+    "RFC6570"
+  ],
+  "author": {
+    "name": "Lee ByeongJun",
+    "email": "lbj199874@gmail.com"
+  },
+  "homepage": "https://fedify.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "packages/uri-template"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fedify-dev/fedify/issues"
+  },
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "require": "./dist/index.d.cts",
+        "default": "./dist/index.d.ts"
+      },
+      "default": {
+        "require": "./dist/index.cjs",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.17.0",
+    "tsdown": "^0.12.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "deno task codegen && tsdown",
+    "prepublish": "pnpm run build",
+    "test": "tsdown && node --experimental-transform-types --test"
+  }
+}