@needle-tools/addressing 0.3.3 → 0.3.4

package/src/target.ts

@@ -0,0 +1,126 @@
+import type { NeedleAddress } from "./address.js";
+
+/**
+ * The canonical STRING form of a document target — the ONE print/parse pair
+ * for `{ ref?, address? }` (plans/one-address-vocabulary.md: one vocabulary;
+ * this is a second wire FORM of it, never a second dialect — no other code
+ * may format or parse these tokens).
+ *
+ * Grammar (rungs optional, fixed order):
+ *
+ *     "@" [ref] [ "/" [type ":"] [id] ["#" anchor] ["~" name] ["!" path] ]
+ *
+ * - `@` leads every token — the RETIRED session grammars ("<uuid>/<path>"
+ *   handles, bare hierarchy ids) can never half-parse as a target; a stale
+ *   token fails loud.
+ * - the `node` type is implicit (omitted on print, re-minted on parse) —
+ *   the canonical form normalizes a type-less address to `type: "node"`.
+ * - ref/id/anchor/name are token-escaped; the PATH rung is last and
+ *   verbatim (it is already the stored escaped form from joinPath and may
+ *   contain any character).
+ */
+
+export type AddressTarget = { ref?: string; address?: NeedleAddress };
+
+// the six characters the grammar reserves (+ "%" as the escape lead) — encoded
+// with %xx so decodeURIComponent inverts; everything else stays raw and human-
+// readable ("$scene" must print as "$scene", not "%24scene")
+function encodeToken(value: string): string {
+    return value
+        .replace(/%/g, "%25")
+        .replace(/\//g, "%2F")
+        .replace(/:/g, "%3A")
+        .replace(/#/g, "%23")
+        .replace(/~/g, "%7E")
+        .replace(/!/g, "%21")
+        .replace(/@/g, "%40");
+}
+
+function decodeToken(value: string): string | null {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null; // a lone "%" — not a token we printed
+    }
+}
+
+/** print a target as its canonical token — null when there is nothing to name */
+export function targetToString(target: AddressTarget): string | null {
+    const address = target.address;
+    const hasAddress = !!address && (address.id !== undefined || address.anchor !== undefined || address.name !== undefined || address.path !== undefined || address.type !== undefined);
+    if (!target.ref && !hasAddress) return null;
+    let token = `@${target.ref ? encodeToken(target.ref) : ""}`;
+    if (hasAddress) {
+        token += "/";
+        const type = address.type ?? "node";
+        if (type !== "node") token += `${encodeToken(type)}:`;
+        if (address.id !== undefined) token += encodeToken(address.id);
+        if (address.anchor !== undefined) token += `#${encodeToken(address.anchor)}`;
+        if (address.name !== undefined) token += `~${encodeToken(address.name)}`;
+        if (address.path !== undefined) token += `!${address.path}`;
+    }
+    return token;
+}
+
+/** parse a canonical token back to the target — null for anything this module
+ * did not print (retired grammars, garbage): a loud miss, never a half-parse */
+export function targetFromString(token: string): AddressTarget | null {
+    if (typeof token !== "string" || !token.startsWith("@") || token.length < 2) return null;
+    const body = token.slice(1);
+    const slash = body.indexOf("/");
+    const refRaw = slash === -1 ? body : body.slice(0, slash);
+    const addrRaw = slash === -1 ? undefined : body.slice(slash + 1);
+    const ref = refRaw.length > 0 ? decodeToken(refRaw) : undefined;
+    if (refRaw.length > 0 && ref === null) return null;
+
+    if (addrRaw === undefined || addrRaw.length === 0) {
+        return ref ? { ref } : null;
+    }
+
+    // consume rungs back to front: path (verbatim remainder), name, anchor
+    let rest = addrRaw;
+    let path: string | undefined;
+    const bang = rest.indexOf("!");
+    if (bang !== -1) {
+        path = rest.slice(bang + 1);
+        rest = rest.slice(0, bang);
+    }
+    let name: string | undefined;
+    const tilde = rest.indexOf("~");
+    if (tilde !== -1) {
+        const decoded = decodeToken(rest.slice(tilde + 1));
+        if (decoded === null) return null;
+        name = decoded;
+        rest = rest.slice(0, tilde);
+    }
+    let anchor: string | undefined;
+    const hash = rest.indexOf("#");
+    if (hash !== -1) {
+        const decoded = decodeToken(rest.slice(hash + 1));
+        if (decoded === null) return null;
+        anchor = decoded;
+        rest = rest.slice(0, hash);
+    }
+    let type = "node";
+    const colon = rest.indexOf(":");
+    if (colon !== -1) {
+        const decoded = decodeToken(rest.slice(0, colon));
+        if (decoded === null || decoded.length === 0) return null;
+        type = decoded;
+        rest = rest.slice(colon + 1);
+    }
+    let id: string | undefined;
+    if (rest.length > 0) {
+        const decoded = decodeToken(rest);
+        if (decoded === null) return null;
+        id = decoded;
+    }
+
+    const address: NeedleAddress = { type };
+    if (id !== undefined) address.id = id;
+    if (anchor !== undefined) address.anchor = anchor;
+    if (name !== undefined) address.name = name;
+    if (path !== undefined) address.path = path;
+    return ref ? { ref, address } : { address };
+}