@webround/commerce 0.0.0-stage → 0.3.0

package/dist/auth/store.js

@@ -0,0 +1,284 @@
+import { canonicalJson } from '../canonical.js';
+import { CommerceError, isCommerceError } from '../errors.js';
+import { requiresTwoFactor } from './types.js';
+/** How long to wait before asking again after a refresh the store could not be reached for: it doubles each time, up to the last. */
+const RETRY_AFTER_MS = [2000, 4000, 8000, 16000, 30000];
+/** Without a JWT (a page that loaded with no network) there is no end to wait for: it stops after this many asks in all (the wake port asks again when the network is back). */
+const RETRIES_WITHOUT_JWT = 10;
+/** The store did not accept the refresh token (it is not there, does not match, ended, was revoked): the customer is not logged in any more. */
+const isRefusal = (error) => isCommerceError(error) && error.kind === 'http' && (error.status === 401 || error.status === 403);
+export function createAuthStore(options) {
+    const { api, storage } = options;
+    const now = options.now ?? Date.now;
+    const renewBefore = options.renewBeforeMs ?? 60000;
+    const timers = options.timers ?? { setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms), clearTimeout: (handle) => globalThis.clearTimeout(handle) };
+    let state = { status: 'unknown', customer: null, challenge: null, error: null };
+    let stateKey = canonicalJson(state);
+    let token = null;
+    let expiresAt = 0;
+    let timer = null;
+    // Counts the times the session was made or ended: an answer that comes after that is about a session that is not this one any more (a refresh under way when the customer logs out)
+    let epoch = 0;
+    // Counts the JWTs the store has been given: two JWTs can be the very same text (the store makes them from the second, the customer and the device), so a new one is told by this and not by its text
+    let given = 0;
+    // How many times in a row a refresh could not reach the store
+    let failures = 0;
+    let refreshing = null;
+    let restoring = null;
+    const listeners = new Set();
+    function set(next) {
+        const merged = { ...state, ...next };
+        const key = canonicalJson(merged);
+        if (key === stateKey)
+            return;
+        state = merged;
+        stateKey = key;
+        // A listener that throws changes nothing here: it is thrown where nobody is waiting on it, so it is seen
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                setTimeout(() => { throw error; }, 0);
+            }
+        }
+    }
+    function stopTimer() {
+        if (timer !== null)
+            timers.clearTimeout(timer);
+        timer = null;
+    }
+    /** The JWT is renewed by itself a little before it ends, so a page that stays open stays logged in. */
+    function schedule() {
+        stopTimer();
+        if (token === null)
+            return;
+        const handle = timers.setTimeout(() => { timer = null; void refresh(); }, Math.max(1000, expiresAt - now() - renewBefore));
+        timer = handle;
+        handle?.unref?.(); // a timer does not keep a script alive
+    }
+    /** A refresh that did not reach the store is asked again, sooner and sooner than the JWT ends, for as long as that JWT is good: a customer whose network is down for a minute is still logged in when it is back. */
+    function retry() {
+        const holding = token !== null;
+        if (holding ? now() >= expiresAt : state.status !== 'unknown' || failures >= RETRIES_WITHOUT_JWT)
+            return;
+        stopTimer();
+        const wait = RETRY_AFTER_MS[Math.min(failures - 1, RETRY_AFTER_MS.length - 1)] ?? 30000;
+        const handle = timers.setTimeout(() => {
+            timer = null;
+            if (state.status === 'unknown')
+                void restore();
+            else
+                void refresh();
+        }, holding ? Math.min(wait, Math.max(1000, expiresAt - now())) : wait);
+        timer = handle;
+        handle?.unref?.();
+    }
+    function takeCustomer(session) {
+        const { token: jwt, expiresIn, ...rest } = session;
+        token = jwt;
+        failures = 0;
+        given++;
+        expiresAt = now() + expiresIn * 1000;
+        const { csrfToken: _csrf, extraData: _extra, ...customer } = rest;
+        return customer;
+    }
+    function accept(session) {
+        epoch++;
+        const customer = takeCustomer(session);
+        storage.saveCsrfToken(session.csrfToken);
+        set({ status: 'signedIn', customer, challenge: null, error: null });
+        schedule();
+    }
+    function endSession() {
+        epoch++;
+        stopTimer();
+        token = null;
+        failures = 0;
+        expiresAt = 0;
+        storage.forgetCsrfToken();
+        set({ status: 'signedOut', customer: null, challenge: null, error: null });
+    }
+    function refresh() {
+        if (refreshing)
+            return refreshing;
+        const csrfToken = storage.csrfToken();
+        if (csrfToken === null) {
+            // Nothing to ask with: whoever was logged in is not any more
+            if (state.status !== 'signingIn' && state.status !== 'challenge')
+                endSession();
+            return Promise.resolve(false);
+        }
+        const mine = epoch;
+        const asked = (async () => {
+            // `refreshing` is set before anything is asked, whatever the api does with the call
+            await Promise.resolve();
+            try {
+                const session = await api.refresh({ deviceId: storage.deviceId() }, { csrfToken });
+                if (epoch !== mine)
+                    return false;
+                const customer = takeCustomer(session);
+                set({ status: 'signedIn', customer, challenge: null, error: null });
+                schedule();
+                return true;
+            }
+            catch (error) {
+                if (epoch !== mine)
+                    return false;
+                if (isRefusal(error)) {
+                    endSession();
+                    return false;
+                }
+                // The store was not reached (or was in trouble): nothing is ended. What was good stays, and the next try may work
+                set({ error: isCommerceError(error) ? error : new CommerceError({ kind: 'network', message: 'The store could not be reached.', cause: error }) });
+                failures++;
+                retry();
+                return token !== null;
+            }
+        })();
+        refreshing = asked;
+        const clear = () => { if (refreshing === asked)
+            refreshing = null; };
+        asked.then(clear, clear);
+        return asked;
+    }
+    function restore() {
+        if (state.status !== 'unknown' && restoring === null)
+            return Promise.resolve();
+        if (restoring)
+            return restoring;
+        const done = (async () => {
+            await Promise.resolve();
+            if (storage.csrfToken() === null) {
+                endSession();
+                return;
+            }
+            await refresh();
+            // Not refused, not reached: it is still not known
+        })();
+        restoring = done;
+        const clear = () => { if (restoring === done)
+            restoring = null; };
+        done.then(clear, clear);
+        return done;
+    }
+    function deviceFields() {
+        return { deviceId: storage.deviceId(), ...(options.device?.platform ? { platform: options.device.platform } : {}), ...(options.device?.region ? { region: options.device.region } : {}) };
+    }
+    /** What an action does while its call is under way, and what it leaves if it fails. */
+    async function acting(call) {
+        const before = state;
+        set({ status: 'signingIn', error: null });
+        try {
+            return await call();
+        }
+        catch (error) {
+            set({ status: before.status === 'signingIn' ? 'signedOut' : before.status, error: null });
+            throw error;
+        }
+    }
+    async function accessToken() {
+        if (state.status === 'unknown')
+            await restore();
+        if (token === null)
+            return null;
+        if (expiresAt - now() > renewBefore)
+            return token;
+        await refresh();
+        return token;
+    }
+    async function renew(rejected) {
+        if (token !== null && token !== rejected)
+            return token;
+        if (token === null)
+            return null;
+        // A renewal that gave no JWT (the store was not reached, or it was refused) is not a JWT to ask again with
+        const before = given;
+        await refresh();
+        return token !== null && given !== before ? token : null;
+    }
+    async function authHeaders() {
+        const jwt = await accessToken();
+        return jwt === null ? {} : { Authorization: `Bearer ${jwt}` };
+    }
+    /** The page is back. A timer did not run while the machine slept, or the page was hidden: the JWT is looked at against the clock, and the next renewal is set from it. */
+    function woke() {
+        if (disposed)
+            return;
+        if (state.status === 'unknown') {
+            void restore();
+            return;
+        }
+        if (state.status !== 'signedIn' || token === null)
+            return;
+        if (expiresAt - now() <= renewBefore)
+            void refresh();
+        else
+            schedule();
+    }
+    let disposed = false;
+    const stopWaking = options.wake?.subscribe(woke);
+    return {
+        getState: () => state,
+        dispose() {
+            disposed = true;
+            stopTimer();
+            stopWaking?.();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        restore,
+        refresh,
+        accept,
+        signup: (input, callOptions) => acting(async () => { accept(await api.signup({ ...input, ...deviceFields() }, callOptions)); }),
+        login: (input) => acting(async () => {
+            const answer = await api.login({ ...input, ...deviceFields() });
+            if (requiresTwoFactor(answer))
+                set({ status: 'challenge', challenge: answer, customer: null, error: null });
+            else
+                accept(answer);
+        }),
+        async verifyTwoFactor(totpCode) {
+            const challenge = state.challenge;
+            if (!challenge)
+                throw new CommerceError({ kind: 'http', message: 'There is no login waiting for a code.', status: null });
+            const before = state;
+            set({ status: 'signingIn' });
+            try {
+                accept(await api.totpLoginVerify({ challengeId: challenge.challengeId, totpCode, ...deviceFields() }));
+            }
+            catch (error) {
+                // The challenge ended (or is not there): there is nothing to answer any more. A wrong code leaves it, to try again
+                if (isCommerceError(error) && error.code === 'TWO_FA_CHALLENGE_NOT_FOUND')
+                    endSession();
+                else
+                    set({ status: before.status, challenge });
+                throw error;
+            }
+        },
+        cancelChallenge() {
+            if (state.status === 'challenge')
+                set({ status: 'signedOut', challenge: null });
+        },
+        async logout() {
+            if (state.status === 'unknown')
+                await restore();
+            if (token !== null) {
+                try {
+                    // The JWT goes in the header; the store ends the refresh token of this device and clears its cookie
+                    await api.logout({ deviceId: storage.deviceId() }, { accessToken: token });
+                }
+                catch {
+                    // The store was not reached: the session ends here all the same (without the CSRF token a refresh cannot be asked for)
+                }
+            }
+            endSession();
+        },
+        accessToken,
+        renew,
+        authHeaders,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/auth/types.d.ts

@@ -0,0 +1,105 @@
+/** What the customer's device says about itself: `deviceId` (made by the client, 5 characters at least) is what the refresh token belongs to. */
+export interface DeviceInput {
+    deviceId: string;
+    /** `web`, `ios`, `android`… */
+    platform?: string;
+    /** `IT`, `FR`… */
+    region?: string;
+}
+export interface SignupInput extends DeviceInput {
+    email: string;
+    /** 8 to 128 characters, with an uppercase letter, a lowercase one, a number and a special character. */
+    password: string;
+    /** The same as `password`. */
+    confirmPassword: string;
+    /** 2 to 64 characters. */
+    displayName: string;
+    phone?: string | null;
+    newsletter?: boolean | null;
+}
+export interface LoginInput extends DeviceInput {
+    email: string;
+    password: string;
+}
+/** The second step of a login whose customer has two-factor authentication on: the code of their authenticator app, for the challenge the login answered. */
+export interface TotpLoginVerifyInput extends DeviceInput {
+    challengeId: string;
+    /** The six digits. */
+    totpCode: string;
+}
+/** Turns two-factor authentication on, after `totpSetup`: the code the app shows for the secret. */
+export interface TotpConfirmInput extends DeviceInput {
+    totpCode: string;
+}
+export interface RefreshInput {
+    deviceId: string;
+}
+export interface LogoutInput {
+    deviceId: string;
+}
+export interface RequestResetInput {
+    email: string;
+}
+/** The address a newsletter subscription or cancellation is about. A logged-in customer's own address is used by the store whatever is sent (it is still required). */
+export interface NewsletterInput {
+    email: string;
+}
+/** What the calls that make the store send an email can say: the language it is written in (the `Accept-Language` of the request). */
+export interface EmailOptions {
+    language?: string;
+}
+/** The customer and their session, as signup, login and the second step of a login answer. */
+export interface AuthSession {
+    customerId: string;
+    email: string;
+    displayName: string | null;
+    emailVerified: boolean;
+    provider: string;
+    /** When the customer was made, as a date in text (ISO). */
+    createdAt: string | null;
+    twoFactorEnabled: boolean;
+    vatExempt: boolean;
+    vatCode: string;
+    newsletter: boolean;
+    /** What the store keeps about the customer: `null` from a login, `{}` from a signup and a refresh. */
+    metadata: unknown;
+    /** The JWT that says who the customer is (`Authorization: Bearer …`): it lasts `expiresIn` seconds (an hour). */
+    token: string;
+    /** Made with the refresh token (the cookie `wrRefreshToken_<storeId>`) and good for as long as it is: a refresh asks for it (`x-wr-csrf`), and does not give a new one. */
+    csrfToken: string;
+    expiresIn: number;
+    /** What a call adds (the recovery codes of a confirmed two-factor setup, for one). */
+    extraData?: unknown;
+}
+/** What a refresh answers: the session again, with a new JWT, and no `csrfToken` (the one the login gave still holds). */
+export type RefreshedSession = Omit<AuthSession, 'csrfToken' | 'extraData'>;
+/** A login of a customer with two-factor authentication on is not a session yet: the code of their app is asked for (`totpLoginVerify`), for this `challengeId`. */
+export interface TwoFactorChallenge {
+    requires2FA: true;
+    challengeId: string;
+    customerId: string;
+    email: string;
+    deviceId: string;
+}
+export type LoginAnswer = AuthSession | TwoFactorChallenge;
+/** Whether a login answered a challenge (two-factor) and not a session. */
+export declare const requiresTwoFactor: (answer: LoginAnswer) => answer is TwoFactorChallenge;
+/**
+ * What subscribing to the newsletter or cancelling answers. `direct: true`: it is done. `direct: false`: the store sent an email with a link to confirm (a guest, or a customer whose address is not verified).
+ * A logged-in customer who is already in the state asked for gets `direct: false` and no email: that is for the screen to know (`customer.newsletter`).
+ */
+export interface NewsletterAnswer {
+    direct: boolean;
+}
+/** What `totpConfirm` answers: the session again (two-factor is now on), with the recovery codes in `extraData.recoveryCodes`: the only time they are given. */
+export type TotpConfirmAnswer = AuthSession & {
+    extraData?: {
+        recoveryCodes?: string[];
+    };
+};
+/** What a customer adds to their authenticator app. */
+export interface TotpSetup {
+    secret: string;
+    otpauthUrl: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.js

@@ -0,0 +1,5 @@
+// What commerce-core takes and answers for a store's customers (`/store-customers/auth/*`), written from what a real store answered (smoke/auth.smoke.ts), not from its OpenAPI or its DTOs: the DTO
+// of the session leaves out `csrfToken`, which the real answer has. Nothing here is a default of the server's: what is not said is for the server to decide.
+/** Whether a login answered a challenge (two-factor) and not a session. */
+export const requiresTwoFactor = (answer) => 'requires2FA' in answer && answer.requires2FA === true;
+//# sourceMappingURL=types.js.map

package/dist/auth/wake.d.ts

@@ -0,0 +1,18 @@
+export interface WakePort {
+    /** Calls `listener` each time the page is back; the function it returns stops that. */
+    subscribe(listener: () => void): () => void;
+}
+interface Target {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+interface Env {
+    window?: Target;
+    document?: Target & {
+        visibilityState?: string;
+    };
+}
+/** The browser's: the tab is visible again, the network is back, or the page is shown again from the back-forward cache. Where there is no window (a server render, a worker) it never says anything. */
+export declare function browserWakePort(env?: Env): WakePort;
+export {};
+//# sourceMappingURL=wake.d.ts.map

package/dist/auth/wake.js

@@ -0,0 +1,23 @@
+// "The page is back", as a port: a timer does not run while a machine sleeps or a tab is frozen, so a session kept good by a timer has to be looked at when the page comes back. The store only knows this one
+// function; the browser, a test and a runtime with no window are all the same to it.
+/** The browser's: the tab is visible again, the network is back, or the page is shown again from the back-forward cache. Where there is no window (a server render, a worker) it never says anything. */
+export function browserWakePort(env = globalThis) {
+    return {
+        subscribe(listener) {
+            const { window: win, document: doc } = env;
+            if (!win || !doc)
+                return () => { };
+            const onVisibility = () => { if (doc.visibilityState === 'visible')
+                listener(); };
+            doc.addEventListener('visibilitychange', onVisibility);
+            win.addEventListener('online', listener);
+            win.addEventListener('pageshow', listener);
+            return () => {
+                doc.removeEventListener('visibilitychange', onVisibility);
+                win.removeEventListener('online', listener);
+                win.removeEventListener('pageshow', listener);
+            };
+        },
+    };
+}
+//# sourceMappingURL=wake.js.map

package/dist/cache.d.ts

@@ -0,0 +1,49 @@
+export type CacheSnapshot<T = unknown> = {
+    status: 'idle';
+} | {
+    status: 'pending';
+} | {
+    status: 'ready';
+    data: T;
+} | {
+    status: 'error';
+    error: unknown;
+};
+export interface LoadOptions {
+    /** To give up on THIS call. Others waiting for the same key are not affected. */
+    signal?: AbortSignal;
+}
+export interface Cache {
+    /**
+     * The answer for a key. `ready`: it is given back, `fetcher` is not called. `pending`: the request under way is joined. `idle` or `error`: `fetcher` is called, once, and the key is
+     * `pending` until it ends. `fetcher` is given a signal that is aborted when nobody is waiting any more.
+     */
+    load<T>(key: string, fetcher: (signal: AbortSignal) => Promise<T>, options?: LoadOptions): Promise<T>;
+    /** The state of a key now. It never starts anything. It is the SAME object until the key changes (so a framework can tell that something did). */
+    snapshot<T = unknown>(key: string): CacheSnapshot<T>;
+    /** Called whenever the state of this key changes, once for each change. Returns what stops it. */
+    subscribe(key: string, listener: () => void): () => void;
+    /**
+     * Forgets the keys that start with `prefix` (all of them with an empty one). A request under way for one of them goes on for whoever waits for it, but what it brings is not kept:
+     * the next `load` asks again.
+     */
+    invalidate(prefix: string): void;
+}
+export declare function createCache(): Cache;
+/** The parts a key is made of: which backend, which store, which call, what it is about (an id, a slug) and what was asked. */
+export interface CacheKeyParts {
+    /** The backend's address. */
+    base: string;
+    storeId: string;
+    /** `products.search`, `products.getReviews`… */
+    call: string;
+    /** What the call is about, when it is about one thing: a product's id, a variant's slug. */
+    subject?: string;
+    /** What was asked, as the call takes it: it is written in its canonical form, so the same question is the same key however it was written. */
+    params?: unknown;
+}
+/** One key for one question. The parts before the params are written so that none holds the separator: a prefix of them (`cachePrefix`) can only match what it names. */
+export declare function cacheKey(parts: CacheKeyParts): string;
+/** The start of the keys of a store, of one call, or of one call about one subject: what `invalidate` takes. It ends with the separator, so `a` does not match `ab`. */
+export declare function cachePrefix(parts: Pick<CacheKeyParts, 'base' | 'storeId'> & Partial<Pick<CacheKeyParts, 'call' | 'subject'>>): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -0,0 +1,144 @@
+import { canonicalJson } from './canonical.js';
+import { CommerceError } from './errors.js';
+const IDLE = { status: 'idle' };
+const aborted = () => new CommerceError({ kind: 'aborted', message: 'The request was cancelled.' });
+export function createCache() {
+    const states = new Map();
+    const flights = new Map();
+    const listeners = new Map();
+    function notify(key) {
+        const set = listeners.get(key);
+        if (!set)
+            return;
+        for (const listener of [...set]) {
+            // A listener that throws must change nothing here: not what the others are told, not what whoever waits is given. It is thrown where nobody is waiting on it, so it is seen
+            try {
+                listener();
+            }
+            catch (error) {
+                setTimeout(() => { throw error; }, 0);
+            }
+        }
+    }
+    function setState(key, state) {
+        if (state === undefined)
+            states.delete(key);
+        else
+            states.set(key, state);
+        notify(key);
+    }
+    /** One caller less is waiting. When none is left, the request is given up and the key is as if it had never been asked. */
+    function release(flight) {
+        flight.waiters--;
+        if (flight.waiters > 0)
+            return;
+        flight.controller.abort();
+        if (flights.get(flight.key) === flight) {
+            flights.delete(flight.key);
+            setState(flight.key, undefined);
+        }
+    }
+    function start(key, fetcher) {
+        const controller = new AbortController();
+        const flight = { key, controller, promise: Promise.resolve(), waiters: 0 };
+        flights.set(key, flight);
+        let asked;
+        try {
+            asked = fetcher(controller.signal);
+        }
+        catch (error) {
+            asked = Promise.reject(error);
+        }
+        flight.promise = asked.then((data) => {
+            // Still the request this key is waiting for (it was not given up, nor forgotten while it was under way): what it brought is kept
+            if (flights.get(key) === flight) {
+                flights.delete(key);
+                setState(key, { status: 'ready', data });
+            }
+            return data;
+        }, (error) => {
+            if (flights.get(key) === flight) {
+                flights.delete(key);
+                setState(key, { status: 'error', error });
+            }
+            throw error;
+        });
+        // Whoever waits is told of the failure; if nobody is (they all gave up), it is not an unhandled one
+        flight.promise.catch(() => undefined);
+        setState(key, { status: 'pending' });
+        return flight;
+    }
+    function join(flight, signal) {
+        flight.waiters++;
+        return new Promise((resolve, reject) => {
+            let over = false;
+            const finish = () => {
+                if (over)
+                    return false;
+                over = true;
+                signal?.removeEventListener('abort', onAbort);
+                return true;
+            };
+            const onAbort = () => {
+                if (!finish())
+                    return;
+                reject(aborted());
+                release(flight);
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            flight.promise.then((data) => { if (finish())
+                resolve(data); }, (error) => { if (finish())
+                reject(error); });
+        });
+    }
+    return {
+        load(key, fetcher, options) {
+            // A call that was given up before it began asks nothing, and is told nothing
+            if (options?.signal?.aborted)
+                return Promise.reject(aborted());
+            const state = states.get(key);
+            if (state?.status === 'ready')
+                return Promise.resolve(state.data);
+            const flight = flights.get(key) ?? start(key, fetcher);
+            return join(flight, options?.signal);
+        },
+        snapshot(key) {
+            return (states.get(key) ?? IDLE);
+        },
+        subscribe(key, listener) {
+            let set = listeners.get(key);
+            if (!set)
+                listeners.set(key, (set = new Set()));
+            set.add(listener);
+            return () => {
+                set.delete(listener);
+                if (set.size === 0 && listeners.get(key) === set)
+                    listeners.delete(key);
+            };
+        },
+        invalidate(prefix) {
+            const keys = [...new Set([...states.keys(), ...flights.keys()])].filter((key) => key.startsWith(prefix));
+            // First everything is forgotten, then those who watch are told: one that reads in its listener finds the cache whole
+            for (const key of keys) {
+                flights.delete(key); // the request goes on for whoever waits for it; what it brings is no longer this key's
+                states.delete(key);
+            }
+            for (const key of keys)
+                notify(key);
+        },
+    };
+}
+const part = (value) => encodeURIComponent(value);
+const baseOf = (base) => base.replace(/\/+$/, '');
+/** One key for one question. The parts before the params are written so that none holds the separator: a prefix of them (`cachePrefix`) can only match what it names. */
+export function cacheKey(parts) {
+    return `${cachePrefix(parts)}${parts.params === undefined ? '' : canonicalJson(parts.params)}`;
+}
+/** The start of the keys of a store, of one call, or of one call about one subject: what `invalidate` takes. It ends with the separator, so `a` does not match `ab`. */
+export function cachePrefix(parts) {
+    const store = `${part(baseOf(parts.base))}|${part(parts.storeId)}|`;
+    if (parts.call === undefined)
+        return store;
+    return `${store}${part(parts.call)}|${parts.subject === undefined ? '' : `${part(parts.subject)}|`}`;
+}
+//# sourceMappingURL=cache.js.map

package/dist/canonical.d.ts

@@ -0,0 +1,7 @@
+export type Canonical = string | number | boolean | null | Canonical[] | {
+    [key: string]: Canonical;
+};
+export declare function canonicalize(value: unknown): Canonical | undefined;
+/** The canonical text of a value: what goes in the body of a request, and what a cache key is made of. */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.js

@@ -0,0 +1,32 @@
+// The same data, written the one way. Two bodies that mean the same thing (`{ a: 1, b: [2, 1] }` and `{ b: [1, 2], a: 1 }`) come out as the same text, so a request is always sent the same way and,
+// one layer up, the same request is the same key. The rules:
+//  - keys are in order, at every depth (by code point: the same everywhere);
+//  - the items of a list are in order too (by their own canonical text). An API for which the order of a list matters is the API's mistake, not something to carry here;
+//  - what is `undefined` is not there; `null` is a value and stays; an empty list stays (it is data: the server's default for "nothing" is not this package's to know);
+//  - what is sent is JSON: numbers, texts, booleans, null, lists and plain objects. Nothing else is looked after (a Date, a Map).
+// The input is never changed.
+export function canonicalize(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => canonicalize(item) ?? null)
+            .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+    }
+    const out = {};
+    for (const key of Object.keys(value).sort(compare)) {
+        const item = canonicalize(value[key]);
+        if (item !== undefined)
+            out[key] = item;
+    }
+    return out;
+}
+/** The canonical text of a value: what goes in the body of a request, and what a cache key is made of. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value) ?? null);
+}
+// By code point, not by the language's collation: `Array.prototype.sort()` with no function is by UTF-16 unit, which is what `<` is too, so this is the same rule written down.
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+//# sourceMappingURL=canonical.js.map