Skip to content

plugin-history-sync: makeTemplate().fill() throws TypeError for dotted or non-ASCII path params and does not percent-encode/decode #778

Open

Description

@trackoor

In @stackflow/plugin-history-sync, makeTemplate().fill() (used by historySyncPlugin when pushing activities or resolving URLs) throws TypeError: Cannot convert undefined or null to object when a path parameter contains . (such as 'v1.2'), non-ASCII characters ('한글'), '/', '?', '#', or '', and parse() leaves percent-encoded path segments undecoded.

npm i @stackflow/plugin-history-sync@2.1.0 @stackflow/core react
node repro.cjs

repro.cjs:

const { makeTemplate } = require("@stackflow/plugin-history-sync");
const t = makeTemplate({ path: "/articles/:articleId" });

for (const articleId of ["v1.2", "한글", "a/b", ""]) {
  try {
    console.log(articleId, "->", t.fill({ articleId }));
  } catch (e) {
    console.log(articleId, "->", `${e.name}: ${e.message}`);
  }
}

console.log("fill space ->", JSON.stringify(t.fill({ articleId: "a b" })));
console.log("parse space ->", t.parse("/articles/a b/"));
console.log("parse encoded ->", t.parse("/articles/%ED%95%9C%EA%B8%80/"));

Actual:

v1.2 -> TypeError: Cannot convert undefined or null to object
한글 -> TypeError: Cannot convert undefined or null to object
a/b -> TypeError: Cannot convert undefined or null to object
 -> TypeError: Cannot convert undefined or null to object
fill space -> "/articles/a b/"
parse space -> { articleId: 'a%20b' }
parse encoded -> { articleId: '%ED%95%9C%EA%B8%80' }

Expected: fill() should not throw TypeError for URL-safe values like 'v1.2' (encodeURIComponent('v1.2') === 'v1.2') or non-ASCII values like '한글', and path parameters should be percent-encoded in fill() and decoded in parse() so parse(fill(params)) preserves parameter values (including 'a b' and '한글'), or at minimum fill() should guard against pattern.match(pathname) returning null.

Versions: @stackflow/plugin-history-sync@2.1.0 (url-pattern@1.0.3) and main (fc5320f), Node.js v26.13.0.

In extensions/plugin-history-sync/src/makeTemplate.ts, fill() passes unencoded params to pattern.stringify() and calls Object.keys(pattern.match(pathname)), which throws whenever a character is outside url-pattern's default segmentValueCharset (a-zA-Z0-9-_~ %), while parse() normalizes via new URL(path, "file://") without decoding matched path segments.

Credit: https://ucsbplse.github.io/

Activity

  1. hamarshehmhmd commented on Nov 15, 2026

    @hamarshehmhmd

    Reproduced on main (fc5320f). The throw doesn't come from stringify(). It's the round trip after it: fill() calls pattern.match(pathname) only to find out which keys are path params. When a value has a char outside url-pattern's segmentValueCharset, the match returns null and Object.keys(null) throws. The pattern already knows its param names (pattern.names, same as variableCount uses), so that match isn't needed at all.

    Patch I tested in extensions/plugin-history-sync/src/makeTemplate.ts: use names instead of re-matching, encodeURIComponent the path values in fill(), and decode them in parse() so parse(fill(x)) gives x back. The _ wildcard is left alone.

    +  const pathParamNames: string[] = (pattern as any).names;
    +
       const variableCount = onlyAsterisk
         ? Number.POSITIVE_INFINITY
    -    : (pattern as any).names.length;
    +    : pathParamNames.length;
    @@ fill(params)
    -      const pathname = pattern.stringify(encodedParams);
    -      const pathParams = pattern.match(pathname);
    +      const pathParams = { ...encodedParams };
    +      pathParamNames.forEach((key) => {
    +        const value = pathParams[key];
    +        if (key !== "_" && typeof value === "string") {
    +          pathParams[key] = encodeURIComponent(value);
    +        }
    +      });
    +      const pathname = pattern.stringify(pathParams);
    
           const searchParamsMap = { ...encodedParams };
    
    -      Object.keys(pathParams).forEach((key) => {
    +      pathParamNames.forEach((key) => {
             delete searchParamsMap[key];
           });
    @@ parse(path)
           const params = {
             ...searchParams,
    -        ...pathParams,
    +        ...decodePathParams(pathParams),
           };
    function decodePathParams<P extends { [key: string]: any }>(pathParams: P): P {
      const decoded: { [key: string]: any } = {};
    
      Object.entries(pathParams).forEach(([key, value]) => {
        if (key === "_" || typeof value !== "string") {
          decoded[key] = value;
          return;
        }
        try {
          decoded[key] = decodeURIComponent(value);
        } catch {
          decoded[key] = value;
        }
      });
    
      return decoded as P;
    }

    With this, fill({ articleId: "한글" }) gives /articles/%ED%95%9C%EA%B8%80/, "a/b" gives /articles/a%2Fb/, and "v1.2" no longer throws. One thing the patch doesn't change: parse("/articles/v1.2/") still returns null, because . isn't in the default segmentValueCharset. Adding . there would fix it, but it changes which URLs match existing routes, so I left it out. Apps can already pass urlPatternOptions: { segmentValueCharset: "a-zA-Z0-9-_~ %." } to historySyncPlugin (checked: url-pattern then matches { articleId: 'v1.2' }). Decoding in parse() is also a small behaviour change: anyone who already runs decodeURIComponent in their own decode would now decode twice, which only matters for values with a literal %.

    Verified with 2 new tests in makeTemplate.spec.ts. One checks fill() for v1.2, 한글, a/b (+ query param) and a b. The other checks the parse(fill()) round trip for 1234, 한글, a/b, a b, 100%, plus parsing an already-encoded URL. Before: 2 failed with TypeError: Cannot convert undefined or null to object. After: the whole plugin-history-sync suite passes (8 suites, 58 tests), and tsc --noEmit and biome check are clean.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions