@vouchington/utils 0.1.0 → 0.2.0

package/README.md

@@ -27,6 +27,8 @@ import { serializeCookie } from '@vouchington/utils/cookies'
   caller to supply every policy attribute. `SameSite=None` requires `Secure`.
 - `collections`, `async`, and `stable-json`: collection deduplication/merging, bounded async mapping,
   and deterministic JSON serialization.
+- `feature-flags`: base64 JSON feature-flag cookie parsing and serialization with caller-injected
+  codecs, cookie names, and size policy.
 - `dates`, `format`, `strings`, and `text-metrics`: UTC-day, duration, formatting, text normalization,
   title casing, and word/sentence helpers.
 - `gtin`, `bigint-ids`, and `validation`: GTIN predicates, canonical positive PostgreSQL bigint IDs,

package/dist/collections.d.mts

@@ -3,6 +3,9 @@ export declare function dedupeByLast<T, K>(items: readonly T[], key: (item: T) =
 export declare function dedupeById<T extends {
     id: string;
 }>(items: readonly T[]): T[];
+export declare function indexById<T extends {
+    id: string;
+}>(values: readonly (T | null | undefined)[]): Record<string, T>;
 export declare function mergePageResultsById<T extends {
     id: string;
 }>(pages?: readonly ({

package/dist/collections.mjs

@@ -14,6 +14,20 @@ export function dedupeByLast(items, key) {
 export function dedupeById(items) {
     return dedupeBy(items, (item) => item.id);
 }
+export function indexById(values) {
+    const indexed = {};
+    for (const value of values) {
+        if (value === null || value === undefined)
+            continue;
+        Object.defineProperty(indexed, value.id, {
+            configurable: true,
+            enumerable: true,
+            value,
+            writable: true,
+        });
+    }
+    return indexed;
+}
 export function mergePageResultsById(pages) {
     return dedupeById((pages ?? []).flatMap((page) => page?.results ?? []));
 }

package/dist/feature-flags.d.mts

@@ -0,0 +1,14 @@
+export type FeatureFlags = Record<string, boolean>;
+export type FeatureFlagCookieCodec = {
+    encodeBase64(value: string): string;
+    decodeBase64(value: string): string;
+};
+export type FeatureFlagCookieOptions = {
+    maxCookieLength?: number;
+};
+export declare const DEFAULT_FEATURE_FLAG_COOKIE_MAX_LENGTH = 4096;
+export declare function extractBooleanFeatureFlags(fields: Record<string, unknown>): FeatureFlags;
+export declare function parseFeatureFlagCookie(cookieValue: string, codec: FeatureFlagCookieCodec, options?: FeatureFlagCookieOptions): FeatureFlags;
+export declare function encodeFeatureFlagCookie(overrides: FeatureFlags, codec: FeatureFlagCookieCodec): string;
+export declare function parseFeatureFlagCookieMaxLength(value: string | undefined, fallback?: number): number;
+export declare function safeFeatureFlagCookiePart(cookieName: string, cookieValue: string | undefined, options?: FeatureFlagCookieOptions): string | null;

package/dist/feature-flags.mjs

@@ -0,0 +1,48 @@
+export const DEFAULT_FEATURE_FLAG_COOKIE_MAX_LENGTH = 4096;
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+export function extractBooleanFeatureFlags(fields) {
+    const flags = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (typeof value === 'boolean') {
+            Object.defineProperty(flags, key, {
+                configurable: true,
+                enumerable: true,
+                value,
+                writable: true,
+            });
+        }
+    }
+    return flags;
+}
+export function parseFeatureFlagCookie(cookieValue, codec, options = {}) {
+    try {
+        if (!isSafeCookieValue(cookieValue, options))
+            return {};
+        const parsed = JSON.parse(codec.decodeBase64(cookieValue));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        return extractBooleanFeatureFlags(parsed);
+    }
+    catch {
+        return {};
+    }
+}
+export function encodeFeatureFlagCookie(overrides, codec) {
+    return codec.encodeBase64(JSON.stringify(overrides));
+}
+export function parseFeatureFlagCookieMaxLength(value, fallback = DEFAULT_FEATURE_FLAG_COOKIE_MAX_LENGTH) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function safeFeatureFlagCookiePart(cookieName, cookieValue, options = {}) {
+    return COOKIE_NAME.test(cookieName) && isSafeCookieValue(cookieValue, options)
+        ? `${cookieName}=${cookieValue}`
+        : null;
+}
+function isSafeCookieValue(value, { maxCookieLength = DEFAULT_FEATURE_FLAG_COOKIE_MAX_LENGTH }) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= maxCookieLength &&
+        BASE64.test(value));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -60,6 +60,11 @@
       "import": "./dist/collections.mjs",
       "default": "./dist/collections.mjs"
     },
+    "./feature-flags": {
+      "types": "./dist/feature-flags.d.mts",
+      "import": "./dist/feature-flags.mjs",
+      "default": "./dist/feature-flags.mjs"
+    },
     "./dates": {
       "types": "./dist/dates.d.mts",
       "import": "./dist/dates.mjs",