@stackframe/stack-shared 2.4.13 → 2.4.14

package/dist/sessions.js

@@ -0,0 +1,127 @@
+import { Store } from "./utils/stores";
+export class AccessToken {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+}
+export class RefreshToken {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+}
+/**
+ * A session represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
+ *
+ * A session never changes which user or session it belongs to, but the tokens may change over time.
+ */
+export class Session {
+    _options;
+    /**
+    * Each session has a session key that depends on the tokens inside. If the session has a refresh token, the session key depends only on the refresh token. If the session does not have a refresh token, the session key depends only on the access token.
+    *
+    * Multiple Session objects may have the same session key, which implies that they represent the same session by the same user. Furthermore, a session's key never changes over the lifetime of a session object.
+    *
+    * This makes session keys useful for caching and indexing sessions.
+    */
+    sessionKey;
+    /**
+     * An access token that is not known to be invalid (ie. may be valid, but may have expired).
+     */
+    _accessToken;
+    _refreshToken;
+    /**
+     * Whether the session as a whole is known to be invalid. Used as a cache to avoid making multiple requests to the server (sessions never go back to being valid after being invalidated).
+     *
+     * Applies to both the access token and the refresh token (it is possible for the access token to be invalid but the refresh token to be valid, in which case the session is still valid).
+     */
+    _knownToBeInvalid = new Store(false);
+    _refreshPromise = null;
+    constructor(_options) {
+        this._options = _options;
+        this._accessToken = new Store(_options.accessToken ? new AccessToken(_options.accessToken) : null);
+        this._refreshToken = _options.refreshToken ? new RefreshToken(_options.refreshToken) : null;
+        this.sessionKey = Session.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });
+    }
+    static calculateSessionKey(ofTokens) {
+        if (ofTokens.refreshToken) {
+            return `refresh-${ofTokens.refreshToken}`;
+        }
+        else if (ofTokens.accessToken) {
+            return `access-${ofTokens.accessToken}`;
+        }
+        else {
+            return "not-logged-in";
+        }
+    }
+    invalidate() {
+        this._accessToken.set(null);
+        this._knownToBeInvalid.set(true);
+    }
+    onInvalidate(callback) {
+        return this._knownToBeInvalid.onChange(() => callback());
+    }
+    async getPotentiallyExpiredTokens() {
+        const accessToken = await this._getPotentiallyExpiredAccessToken();
+        return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
+    }
+    async getNewlyFetchedTokens() {
+        const accessToken = await this._getNewlyFetchedAccessToken();
+        return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
+    }
+    markAccessTokenExpired(accessToken) {
+        if (this._accessToken.get() === accessToken) {
+            this._accessToken.set(null);
+        }
+    }
+    /**
+     * Note that a callback invocation with `null` does not mean the session has been invalidated; the access token may just have expired. Use `onInvalidate` to detect invalidation.
+     */
+    onAccessTokenChange(callback) {
+        return this._accessToken.onChange(callback);
+    }
+    /**
+     * @returns An access token (cached if possible), or null if the session either does not represent a user or the session is invalid.
+     */
+    async _getPotentiallyExpiredAccessToken() {
+        const oldAccessToken = this._accessToken.get();
+        if (oldAccessToken)
+            return oldAccessToken;
+        if (!this._refreshToken)
+            return null;
+        if (this._knownToBeInvalid.get())
+            return null;
+        // refresh access token
+        if (!this._refreshPromise) {
+            this._refreshAndSetRefreshPromise(this._refreshToken);
+        }
+        return await this._refreshPromise;
+    }
+    /**
+     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     *
+     * @returns A newly fetched access token (never read from cache), or null if the session either does not represent a user or the session is invalid.
+     */
+    async _getNewlyFetchedAccessToken() {
+        if (!this._refreshToken)
+            return null;
+        if (this._knownToBeInvalid.get())
+            return null;
+        this._refreshAndSetRefreshPromise(this._refreshToken);
+        return await this._refreshPromise;
+    }
+    _refreshAndSetRefreshPromise(refreshToken) {
+        let refreshPromise = this._options.refreshAccessTokenCallback(refreshToken).then((accessToken) => {
+            if (refreshPromise === this._refreshPromise) {
+                this._refreshPromise = null;
+                this._accessToken.set(accessToken);
+                if (!accessToken) {
+                    this.invalidate();
+                }
+            }
+            return accessToken;
+        });
+        this._refreshPromise = refreshPromise;
+    }
+}

package/dist/utils/crypto.js

@@ -1,4 +1,5 @@
 import { encodeBase32 } from "./bytes";
+import { globalVar } from "./globals";
 /**
  * Generates a secure alphanumeric string using the system's cryptographically secure
  * random number generator.
@@ -6,7 +7,7 @@ import { encodeBase32 } from "./bytes";
 export function generateSecureRandomString(minBitsOfEntropy = 224) {
     const base32CharactersCount = Math.ceil(minBitsOfEntropy / 5);
     const bytesCount = Math.ceil(base32CharactersCount * 5 / 8);
-    const randomBytes = globalThis.crypto.getRandomValues(new Uint8Array(bytesCount));
+    const randomBytes = globalVar.crypto.getRandomValues(new Uint8Array(bytesCount));
     const str = encodeBase32(randomBytes);
     return str.slice(str.length - base32CharactersCount).toLowerCase();
 }

package/dist/utils/dom.js

@@ -4,5 +4,5 @@ export function hasClickableParent(element) {
         return false;
     if (parent.dataset.n2Clickable)
         return true;
-    return !!element.parentElement && hasClickableParent(element.parentElement);
+    return hasClickableParent(element.parentElement);
 }

package/dist/utils/env.d.ts

@@ -1,3 +1,4 @@
+export declare function isBrowserLike(): boolean;
 /**
  * Returns the environment variable with the given name, throwing an error if it's undefined or the empty string.
  */

package/dist/utils/env.js

@@ -1,10 +1,13 @@
 import { throwErr } from "./errors";
 import { deindent } from "./strings";
+export function isBrowserLike() {
+    return typeof window !== "undefined" && typeof document !== "undefined" && typeof document.createElement !== "undefined";
+}
 /**
  * Returns the environment variable with the given name, throwing an error if it's undefined or the empty string.
  */
 export function getEnvVariable(name) {
-    if (typeof window !== 'undefined') {
+    if (isBrowserLike()) {
         throw new Error(deindent `
       Can't use getEnvVariable on the client because Next.js transpiles expressions of the kind process.env.XYZ at build-time on the client.
     

package/dist/utils/errors.js

@@ -1,3 +1,4 @@
+import { globalVar } from "./globals";
 export function throwErr(...args) {
     if (typeof args[0] === "string") {
         throw new StackAssertionError(args[0], args[1]);
@@ -29,6 +30,10 @@ export function registerErrorSink(sink) {
 registerErrorSink((location, ...args) => {
     console.error(`Error in ${location}:`, ...args);
 });
+registerErrorSink((location, error, ...args) => {
+    globalVar.stackCapturedErrors = globalVar.stackCapturedErrors ?? [];
+    globalVar.stackCapturedErrors.push({ location, error: args, extraArgs: args });
+});
 export function captureError(location, error) {
     for (const sink of errorSinks) {
         sink(location, error);

package/dist/utils/globals.js

@@ -1,6 +1,6 @@
 const globalVar = typeof globalThis !== 'undefined' ? globalThis :
-    typeof window !== 'undefined' ? window :
-        typeof global !== 'undefined' ? global :
+    typeof global !== 'undefined' ? global :
+        typeof window !== 'undefined' ? window :
             typeof self !== 'undefined' ? self :
                 {};
 export { globalVar, };

package/dist/utils/promises.d.ts

@@ -18,8 +18,10 @@ export declare function pending<T>(promise: Promise<T>, options?: {
 }): ReactPromise<T>;
 export declare function wait(ms: number): Promise<void>;
 export declare function waitUntil(date: Date): Promise<void>;
+export declare function runAsynchronouslyWithAlert(...args: Parameters<typeof runAsynchronously>): void;
 export declare function runAsynchronously(promiseOrFunc: void | Promise<unknown> | (() => void | Promise<unknown>) | undefined, options?: {
-    ignoreErrors?: boolean;
+    noErrorLogging?: boolean;
+    onError?: (error: Error) => void;
 }): void;
 declare class TimeoutError extends Error {
     readonly ms: number;

package/dist/utils/promises.js

@@ -75,6 +75,15 @@ class ErrorDuringRunAsynchronously extends Error {
         this.name = "ErrorDuringRunAsynchronously";
     }
 }
+export function runAsynchronouslyWithAlert(...args) {
+    return runAsynchronously(args[0], {
+        ...args[1],
+        onError: error => {
+            alert(`An unhandled error occurred. Please ${process.env.NODE_ENV === "development" ? `check the browser console for the full error. ${error}` : "report this to the developer."}`);
+            args[1]?.onError?.(error);
+        },
+    }, ...args.slice(2));
+}
 export function runAsynchronously(promiseOrFunc, options = {}) {
     if (typeof promiseOrFunc === "function") {
         promiseOrFunc = promiseOrFunc();
@@ -86,7 +95,8 @@ export function runAsynchronously(promiseOrFunc, options = {}) {
         }, {
             cause: error,
         });
-        if (!options.ignoreErrors) {
+        options.onError?.(newError);
+        if (!options.noErrorLogging) {
             captureError("runAsynchronously", newError);
         }
     });

package/dist/utils/proxies.d.ts

@@ -0,0 +1 @@
+export declare function logged<T extends object>(name: string, toLog: T, options?: {}): T;

package/dist/utils/proxies.js

@@ -0,0 +1,59 @@
+import { nicify } from "./strings";
+export function logged(name, toLog, options = {}) {
+    const proxy = new Proxy(toLog, {
+        get(target, prop, receiver) {
+            const orig = Reflect.get(target, prop, receiver);
+            if (typeof orig === "function") {
+                return function (...args) {
+                    const success = (v, isPromise) => console.debug(`logged(...): Called ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")}) => ${isPromise ? "Promise<" : ""}${nicify(result)}${isPromise ? ">" : ""}`, { this: this, args, promise: isPromise ? result : false, result: v, trace: new Error() });
+                    const error = (e, isPromise) => console.debug(`logged(...): Error in ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")})`, { this: this, args, promise: isPromise ? result : false, error: e, trace: new Error() });
+                    let result;
+                    try {
+                        result = orig.apply(this, args);
+                    }
+                    catch (e) {
+                        error(e, false);
+                        throw e;
+                    }
+                    if (result instanceof Promise) {
+                        result.then((v) => success(v, true)).catch((e) => error(e, true));
+                    }
+                    else {
+                        success(result, false);
+                    }
+                    return result;
+                };
+            }
+            return orig;
+        },
+        set(target, prop, value) {
+            console.log(`Setting ${name}.${String(prop)} to ${value}`);
+            return Reflect.set(target, prop, value);
+        },
+        apply(target, thisArg, args) {
+            console.log(`Calling ${name}(${JSON.stringify(args).slice(1, -1)})`);
+            return Reflect.apply(target, thisArg, args);
+        },
+        construct(target, args, newTarget) {
+            console.log(`Constructing ${name}(${JSON.stringify(args).slice(1, -1)})`);
+            return Reflect.construct(target, args, newTarget);
+        },
+        defineProperty(target, prop, descriptor) {
+            console.log(`Defining ${name}.${String(prop)} as ${JSON.stringify(descriptor)}`);
+            return Reflect.defineProperty(target, prop, descriptor);
+        },
+        deleteProperty(target, prop) {
+            console.log(`Deleting ${name}.${String(prop)}`);
+            return Reflect.deleteProperty(target, prop);
+        },
+        setPrototypeOf(target, prototype) {
+            console.log(`Setting prototype of ${name} to ${prototype}`);
+            return Reflect.setPrototypeOf(target, prototype);
+        },
+        preventExtensions(target) {
+            console.log(`Preventing extensions of ${name}`);
+            return Reflect.preventExtensions(target);
+        },
+    });
+    return proxy;
+}

package/dist/utils/react.js

@@ -1,6 +1,7 @@
 import { use } from "react";
 import { neverResolve } from "./promises";
 import { deindent } from "./strings";
+import { isBrowserLike } from "./env";
 export function getNodeText(node) {
     if (["number", "string"].includes(typeof node)) {
         return `${node}`;
@@ -29,7 +30,7 @@ export function suspend() {
  * Use this in a component or a hook to disable SSR. Should be wrapped in a Suspense boundary, or it will throw an error.
  */
 export function suspendIfSsr(caller) {
-    if (typeof window === "undefined") {
+    if (!isBrowserLike()) {
         const error = Object.assign(new Error(deindent `
         ${caller ?? "This code path"} attempted to display a loading indicator during SSR by falling back to the nearest Suspense boundary. If you see this error, it means no Suspense boundary was found, and no loading indicator could be displayed. Make sure you are not catching this error with try-catch, and that the component is rendered inside a Suspense boundary, for example by adding a \`loading.tsx\` file in your app directory.
 

package/dist/utils/results.d.ts

@@ -5,11 +5,11 @@ export type Result<T, E = unknown> = {
     status: "error";
     error: E;
 };
-export type AsyncResult<T, E = unknown, P = void> = Result<T, E> | {
+export type AsyncResult<T, E = unknown, P = void> = Result<T, E> | ({
     status: "pending";
 } & {
     progress: P;
-};
+});
 export declare const Result: {
     fromThrowing: typeof fromThrowing;
     fromPromise: typeof promiseToResult;
@@ -62,7 +62,7 @@ declare function promiseToResult<T>(promise: Promise<T>): Promise<Result<T>>;
 declare function fromThrowing<T>(fn: () => T): Result<T, unknown>;
 declare function mapResult<T, U, E = unknown, P = unknown>(result: Result<T, E>, fn: (data: T) => U): Result<U, E>;
 declare function mapResult<T, U, E = unknown, P = unknown>(result: AsyncResult<T, E, P>, fn: (data: T) => U): AsyncResult<U, E, P>;
-declare class RetryError extends Error {
+declare class RetryError extends AggregateError {
     readonly errors: unknown[];
     constructor(errors: unknown[]);
     get retries(): number;

package/dist/utils/results.js

@@ -1,4 +1,5 @@
 import { wait } from "./promises";
+import { deindent } from "./strings";
 export const Result = {
     fromThrowing,
     fromPromise: promiseToResult,
@@ -83,10 +84,17 @@ function mapResult(result, fn) {
         };
     return Result.ok(fn(result.data));
 }
-class RetryError extends Error {
+class RetryError extends AggregateError {
     errors;
     constructor(errors) {
-        super(`Error after retrying ${errors.length} times.`, { cause: errors[errors.length - 1] });
+        super(errors, deindent `
+      Error after retrying ${errors.length} times.
+      
+      ${errors.map((e, i) => deindent `
+        Attempt ${i + 1}:
+          ${e}
+      `).join("\n\n")}
+      `, { cause: errors[errors.length - 1] });
         this.errors = errors;
         this.name = "RetryError";
     }

package/dist/utils/stores.d.ts

@@ -1,5 +1,28 @@
 import { AsyncResult, Result } from "./results";
 import { ReactPromise } from "./promises";
+export type ReadonlyStore<T> = {
+    get(): T;
+    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+};
+export declare class Store<T> implements ReadonlyStore<T> {
+    private _value;
+    private readonly _callbacks;
+    constructor(_value: T);
+    get(): T;
+    set(value: T): void;
+    update(updater: (value: T) => T): T;
+    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+}
 export type ReadonlyAsyncStore<T> = {
     isAvailable(): boolean;
     get(): AsyncResult<T, unknown, void>;

package/dist/utils/stores.js

@@ -1,6 +1,42 @@
 import { AsyncResult, Result } from "./results";
 import { generateUuid } from "./uuids";
 import { pending, rejected, resolved } from "./promises";
+export class Store {
+    _value;
+    _callbacks = new Map();
+    constructor(_value) {
+        this._value = _value;
+    }
+    get() {
+        return this._value;
+    }
+    set(value) {
+        const oldValue = this._value;
+        this._value = value;
+        this._callbacks.forEach((callback) => callback(value, oldValue));
+    }
+    update(updater) {
+        const value = updater(this._value);
+        this.set(value);
+        return value;
+    }
+    onChange(callback) {
+        const uuid = generateUuid();
+        this._callbacks.set(uuid, callback);
+        return {
+            unsubscribe: () => {
+                this._callbacks.delete(uuid);
+            },
+        };
+    }
+    onceChange(callback) {
+        const { unsubscribe } = this.onChange((...args) => {
+            unsubscribe();
+            callback(...args);
+        });
+        return { unsubscribe };
+    }
+}
 export class AsyncStore {
     _isAvailable;
     _value = undefined;

package/dist/utils/strings.d.ts

@@ -39,3 +39,6 @@ export declare function trimLines(s: string): string;
 export declare function templateIdentity(strings: TemplateStringsArray | readonly string[], ...values: any[]): string;
 export declare function deindent(code: string): string;
 export declare function deindent(strings: TemplateStringsArray | readonly string[], ...values: any[]): string;
+export declare function nicify(value: unknown, { depth }?: {
+    depth?: number | undefined;
+}): string;

package/dist/utils/strings.js

@@ -92,3 +92,49 @@ export function deindent(strings, ...values) {
     });
     return templateIdentity(deindentedStrings, ...indentedValues);
 }
+export function nicify(value, { depth = 5 } = {}) {
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+        case "number": {
+            return JSON.stringify(value);
+        }
+        case "undefined": {
+            return "undefined";
+        }
+        case "symbol": {
+            return value.toString();
+        }
+        case "bigint": {
+            return `${value}n`;
+        }
+        case "function": {
+            if (value.name)
+                return `function ${value.name}(...) { ... }`;
+            return `(...) => { ... }`;
+        }
+        case "object": {
+            if (value === null)
+                return "null";
+            if (Array.isArray(value)) {
+                if (depth <= 0 && value.length !== 0)
+                    return "[...]";
+                return `[${value.map((v) => nicify(v, { depth: depth - 1 })).join(", ")}]`;
+            }
+            const entries = Object.entries(value);
+            if (entries.length === 0)
+                return "{}";
+            if (depth <= 0)
+                return "{...}";
+            return `{ ${Object.entries(value).map(([k, v]) => {
+                if (typeof v === "function" && v.name === k)
+                    return `${k}(...): { ... }`;
+                else
+                    return `${k}: ${nicify(v, { depth: depth - 1 })}`;
+            }).join(", ")} }`;
+        }
+        default: {
+            return `${typeof value}<${value}>`;
+        }
+    }
+}

package/dist/utils/uuids.d.ts

@@ -1 +1 @@
-export declare function generateUuid(): string;
+export declare function generateUuid(): any;

package/dist/utils/uuids.js

@@ -1,3 +1,4 @@
+import { globalVar } from "./globals";
 export function generateUuid() {
-    return globalThis.crypto.randomUUID();
+    return globalVar.crypto.randomUUID();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.4.13",
+  "version": "2.4.14",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [