@vouchington/utils 0.5.2 → 0.5.3

package/README.md

@@ -11,12 +11,16 @@ import { buildSignatureHeaders, verifySignature } from '@vouchington/utils/http-
 import { bestAcceptLanguageMatch } from '@vouchington/utils/language-tags'
 import { createMessageTranslator } from '@vouchington/utils/message-catalog'
 import { createReportInputParser } from '@vouchington/utils/moderation'
+import { cacheTag, decodeCacheTagPathSegment } from '@vouchington/utils/cache-tags'
 import { getSentryEnvelopeDiagnostics } from '@vouchington/utils/sentry-envelope'
 import { createScopeCatalog } from '@vouchington/utils/scopes'
 ```
 
 ## Subpaths
 
+- `cache-tags`: canonical printable-ASCII wire encoding, one-segment URL decoding, validation,
+  and escape-boundary truncation. Applications own family names, route recognition, and purge policy.
+  Single-tag validation rejects spaces and comma separators; raw commas are percent-encoded.
 - `sentry-envelope`: bounded UTF-8 envelope record scanning and safe item-type diagnostics.
   Callers choose the byte and type-list limits; DSN, tunnel, request, and logging policy stay local.
 - `scopes`: caller-owned scope catalog validation, prerequisite expansion, audience and surface

package/dist/cache-tags.d.mts

@@ -0,0 +1,10 @@
+/** Maximum accepted Cache-Tag byte length at the wire boundary. */
+export declare const MAX_CACHE_TAG_BYTES = 1024;
+/** Check whether one tag is printable ASCII without spaces or commas and fits the wire limit. */
+export declare function isValidCacheTag(tag: string): boolean;
+/** Decode exactly one URL pathname segment. Never pass raw database values through this function. */
+export declare function decodeCacheTagPathSegment(segment: string): string;
+/** Encode a raw identifier; percent escapes in raw values remain literal identifier text. */
+export declare function encodeCacheTagValue(value: string): string;
+/** Mint a bounded tag for a caller supplied family and raw identifier. */
+export declare function cacheTag(family: string, value: string): string;

package/dist/cache-tags.mjs

@@ -0,0 +1,40 @@
+import { normalizeKey } from './strings.mjs';
+/** Maximum accepted Cache-Tag byte length at the wire boundary. */
+export const MAX_CACHE_TAG_BYTES = 1024;
+const CACHE_TAG_CHARSET = /^[\x21-\x2b\x2d-\x7e]+$/;
+/** Check whether one tag is printable ASCII without spaces or commas and fits the wire limit. */
+export function isValidCacheTag(tag) {
+    return tag.length > 0 && tag.length <= MAX_CACHE_TAG_BYTES && CACHE_TAG_CHARSET.test(tag);
+}
+/** Decode exactly one URL pathname segment. Never pass raw database values through this function. */
+export function decodeCacheTagPathSegment(segment) {
+    if (!segment.includes('%'))
+        return segment;
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/** Encode a raw identifier; percent escapes in raw values remain literal identifier text. */
+export function encodeCacheTagValue(value) {
+    return encodeURIComponent(normalizeKey(value)).toLowerCase();
+}
+/** Mint a bounded tag for a caller supplied family and raw identifier. */
+export function cacheTag(family, value) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(family) || family.length >= MAX_CACHE_TAG_BYTES) {
+        throw new TypeError('Cache tag family must be a bounded lowercase ASCII token');
+    }
+    return truncateCacheTag(`${family}:${encodeCacheTagValue(value)}`);
+}
+function truncateCacheTag(tag) {
+    if (tag.length <= MAX_CACHE_TAG_BYTES)
+        return tag;
+    let end = MAX_CACHE_TAG_BYTES;
+    if (tag[end - 1] === '%')
+        end -= 1;
+    else if (tag[end - 2] === '%')
+        end -= 2;
+    return tag.slice(0, end);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -20,6 +20,11 @@
   ],
   "type": "module",
   "exports": {
+    "./cache-tags": {
+      "types": "./dist/cache-tags.d.mts",
+      "import": "./dist/cache-tags.mjs",
+      "default": "./dist/cache-tags.mjs"
+    },
     "./sentry-envelope": {
       "types": "./dist/sentry-envelope.d.mts",
       "import": "./dist/sentry-envelope.mjs",