liaise 5.0.1 → 5.0.2

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.2] — 2026-10-04
+
+### Fixed
+
+- **A path parameter with no usable value is refused instead of sent.** A token
+  was filled with `String(value)` unchecked, so `getUser({ id: undefined })` on
+  `/users/:id` fetched `/users/undefined`, and `null`, `''`, an object or an array
+  built `/users/null`, `/users/`, `/users/%5Bobject%20Object%5D` or `/users/1%2C2`.
+  The usual cause is a component rendering before the id has loaded. Such a call
+  now returns an error Result (`kind: 'network'`, a `TypeError` naming each bad
+  param, e.g. `Path parameter "id" is undefined in path "/users/:id", so the call
+  was not sent.`) and nothing reaches the server. Accepted values are non-empty
+  strings, finite numbers, bigints and booleans; a `Date` is refused with a hint
+  to convert it first (`toISOString()` or `getTime()`), as in a query string.
+  `NaN` and `Infinity` are refused too. See
+  [MIGRATION.md](./MIGRATION.md#upgrading-to-502).
+
+### Changed
+
+- The README's size figures are re-measured with `npm run size`: about 5.8 kB
+  gzipped for a REST-only import, 6.9 kB for the core entry, 8.0 kB with all
+  middleware (the new check and its error messages add about 0.2 kB).
+
 ## [5.0.1] — 2026-10-03
 
 A bug-fix release from an audit of 5.0.0. Nothing in the API changes; a few calls
@@ -1008,6 +1031,7 @@ Initial release of the rewritten client. Reconstructed from the release commit
   `ArrayBuffer` and strings
 - Response parsing as `json`, `text`, `blob`, `arrayBuffer` or `formData`
 
+[5.0.2]: https://github.com/iremlopsum/liaise/compare/v5.0.1...v5.0.2
 [5.0.1]: https://github.com/iremlopsum/liaise/compare/v5.0.0...v5.0.1
 [5.0.0]: https://github.com/iremlopsum/liaise/compare/v4.4.3...v5.0.0
 [4.4.3]: https://github.com/iremlopsum/liaise/compare/v4.4.2...v4.4.3

package/MIGRATION.md

@@ -7,6 +7,16 @@ For the full record of what changed in each release, see [CHANGELOG.md](./CHANGE
 
 ---
 
+## Upgrading to 5.0.2
+
+No code changes needed. A call whose path parameter is `undefined`, `null`, an
+empty string, an object, an array, a `Date`, a function, a symbol, `NaN` or `Infinity` now returns an
+error Result instead of being sent to a URL like `/users/undefined`. Those calls
+were already hitting the wrong URL; now they say so. If you relied on a literal
+`null` or `undefined` segment, pass the string (`'null'`) explicitly.
+
+---
+
 ## Upgrading to 5.0.1
 
 No code changes for most callers. Six things you may observe.

package/README.md

@@ -11,7 +11,7 @@ Runtime-agnostic, type-safe HTTP client for REST and GraphQL. Built on standard
 - **Composable middleware** — retry, cache, dedupe, auth, logging — applied at global, per-endpoint, or per-call level
 - **Types by inference** — declare params and response once on the endpoint definition; types flow to every call site automatically
 - **Runtime-agnostic** — Node.js 20+, browsers, Bun, Deno, Cloudflare Workers, React Native (its built-in `fetch`; not tested in CI) — any environment with `fetch`
-- **Tiny** — about **5.6 kB gzipped** for a REST-only import, 6.7 kB for the core entry, 7.8 kB with all middleware (measured by `npm run size`); tree-shaking drops what you do not import
+- **Tiny** — about **5.8 kB gzipped** for a REST-only import, 6.9 kB for the core entry, 8.0 kB with all middleware (measured by `npm run size`); tree-shaking drops what you do not import
 
 ```
 npm install liaise
@@ -135,6 +135,8 @@ const getItem = new Request<{ orgId: string; id: string }, Item>({
 await api.getItem({ orgId: 'acme', id: '42' })
 ```
 
+A path parameter must be a non-empty string, a finite number, a bigint or a boolean. Anything else (`undefined`, `null`, `''`, an object, an array, a `Date`, `NaN`) is refused before the request is sent, with an error Result naming the parameter. This catches the common front-end mistake of calling before an id has loaded: `getItem({ orgId: 'acme', id: undefined })` returns an error instead of fetching `/orgs/acme/items/undefined`.
+
 #### `responseType`
 
 Controls how the response body is parsed. Defaults to `'json'`.

package/dist/utils/path-params.d.ts

@@ -56,10 +56,12 @@ export declare class FragmentError extends TypeError {
  * This is the main URL construction function used by the request engine.
  * It handles the full lifecycle from path template to final URL.
  *
- * **Path param matching** uses regex with a word-boundary lookahead to prevent
- * partial matches. For example, a param key `id` will match `:id` but NOT
- * `:idExtra`. This is achieved by requiring that the character after the param
- * name is either a non-alphanumeric-underscore character or end of string.
+ * **Path param matching** scans the template once for `:name` tokens
+ * (`[a-zA-Z0-9_]+`, greedy), so a param key `id` fills `:id` but never part of
+ * `:idExtra`. A token is filled only from a non-empty string, a finite number,
+ * a bigint or a boolean; `undefined`, `null`, `''`, objects, arrays and Dates
+ * throw a TypeError naming the param, so a call is never sent to
+ * '/users/undefined'.
  *
  * **Query string rules** (when `asQuery` is true):
  * - Primitives: `{ page: 1 }` → `?page=1`

package/dist/utils/path-params.js

@@ -25,17 +25,44 @@ export class FragmentError extends TypeError {
         this.resolvedUrl = resolvedUrl;
     }
 }
+function unusableSegment(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (value === '')
+        return 'an empty string';
+    if (typeof value === 'number' && !Number.isFinite(value))
+        return String(value);
+    if (value instanceof Date)
+        return 'a Date (convert it first, e.g. date.toISOString() or date.getTime())';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'function' || typeof value === 'symbol')
+        return `a ${typeof value}`;
+    return null;
+}
 export function buildUrl(baseUrl, path, params, asQuery = false) {
     const fragmentIn = path.includes('#') ? { where: 'path', value: path } : baseUrl.includes('#') ? { where: 'baseUrl', value: baseUrl } : null;
     let resolvedPath = path;
     const remaining = {};
     const lookup = new Map(Object.entries(params));
     const consumed = new Set();
+    const unusable = [];
     resolvedPath = resolvedPath.replace(/:([a-zA-Z0-9_]+)/g, (token, name) => {
         if (!lookup.has(name))
             return token;
         consumed.add(name);
-        return encodeURIComponent(String(lookup.get(name)));
+        const value = lookup.get(name);
+        const problem = unusableSegment(value);
+        if (problem) {
+            if (!unusable.some(entry => entry.startsWith(`"${name}"`)))
+                unusable.push(`"${name}" is ${problem}`);
+            return token;
+        }
+        return encodeURIComponent(String(value));
     });
     for (const [key, value] of lookup) {
         if (!consumed.has(key))
@@ -46,6 +73,10 @@ export function buildUrl(baseUrl, path, params, asQuery = false) {
         throw new FragmentError(`A URL fragment is never sent to the server, so it cannot appear in a ${fragmentIn.where}. ` +
             `Remove "${fragment}" from "${fragmentIn.value}".`, joinUrl(baseUrl, resolvedPath));
     }
+    if (unusable.length > 0) {
+        throw new TypeError(`Path parameter ${unusable.join(', ')} in path "${path}", so the call was not sent. ` +
+            'A path parameter must be a non-empty string, a finite number, a bigint or a boolean.');
+    }
     const unresolved = resolvedPath
         .split('/')
         .map(segment => /^:[a-zA-Z0-9_]+/.exec(segment)?.[0])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liaise",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "Type-safe API client for REST and GraphQL on standard fetch. Never throws. Zero dependencies.",
   "type": "module",
   "sideEffects": false,