@stackframe/stack-shared 2.8.56 → 2.8.59

package/dist/esm/sessions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/sessions.ts"],"sourcesContent":["import * as jose from 'jose';\nimport { InferType } from 'yup';\nimport { accessTokenPayloadSchema } from './schema-fields';\nimport { StackAssertionError, throwErr } from \"./utils/errors\";\nimport { Store } from \"./utils/stores\";\n\n\nexport type AccessTokenPayload = InferType<typeof accessTokenPayloadSchema>;\n\nfunction decodeAccessTokenIfValid(token: string): AccessTokenPayload | null {\n  try {\n    const payload = jose.decodeJwt(token);\n    return accessTokenPayloadSchema.validateSync(payload);\n  } catch (e) {\n    return null;\n  }\n}\n\nexport class AccessToken {\n  static createIfValid(token: string): AccessToken | null {\n    const payload = decodeAccessTokenIfValid(token);\n    if (!payload) return null;\n    return new AccessToken(token);\n  }\n\n  private constructor(\n    public readonly token: string,\n  ) {\n    if (token === \"undefined\") {\n      throw new StackAssertionError(\"Access token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!\");\n    }\n  }\n\n  get payload() {\n    return decodeAccessTokenIfValid(this.token) ?? throwErr(\"Invalid access token in payload (should've been validated in createIfValid)\", { token: this.token });\n  }\n\n  get expiresAt(): Date {\n    const { exp } = this.payload;\n    if (exp === undefined) return new Date(8640000000000000);  // max date value\n    return new Date(exp * 1000);\n  }\n\n  /**\n   * @returns The number of milliseconds until the access token expires, or 0 if it has already expired.\n   */\n  get expiresInMillis(): number {\n    return Math.max(0, this.expiresAt.getTime() - Date.now());\n  }\n\n  isExpired(): boolean {\n    return this.expiresInMillis <= 0;\n  }\n}\n\nexport class RefreshToken {\n  constructor(\n    public readonly token: string,\n  ) {\n    if (token === \"undefined\") {\n      throw new StackAssertionError(\"Refresh token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!\");\n    }\n  }\n}\n\n/**\n * An InternalSession represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.\n *\n * A session never changes which user or session it belongs to, but the tokens in it may change over time.\n */\nexport class InternalSession {\n  /**\n  * 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.\n  *\n  * 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.\n  *\n  * This is useful for caching and indexing sessions.\n  */\n  public readonly sessionKey: string;\n\n  /**\n   * An access token that is not known to be invalid (ie. may be valid, but may have expired).\n   */\n  private _accessToken: Store<AccessToken | null>;\n  private readonly _refreshToken: RefreshToken | null;\n\n  /**\n   * Whether the session as a whole is known to be invalid (ie. both access and refresh tokens are invalid). Used as a cache to avoid making multiple requests to the server (sessions never go back to being valid after being invalidated).\n   *\n   * It is possible for the access token to be invalid but the refresh token to be valid, in which case the session is\n   * still valid (just needs a refresh). It is also possible for the access token to be valid but the refresh token to\n   * be invalid, in which case the session is also valid (eg. if the refresh token is null because the user only passed\n   * in an access token, eg. in a server-side request handler).\n   */\n  private _knownToBeInvalid = new Store<boolean>(false);\n\n  private _refreshPromise: Promise<AccessToken | null> | null = null;\n\n  constructor(private readonly _options: {\n    refreshAccessTokenCallback(refreshToken: RefreshToken): Promise<AccessToken | null>,\n    refreshToken: string | null,\n    accessToken?: string | null,\n  }) {\n    this._accessToken = new Store(_options.accessToken ? AccessToken.createIfValid(_options.accessToken) : null);\n    this._refreshToken = _options.refreshToken ? new RefreshToken(_options.refreshToken) : null;\n    if (_options.accessToken === null && _options.refreshToken === null) {\n      // this session is already invalid\n      this._knownToBeInvalid.set(true);\n    }\n    this.sessionKey = InternalSession.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });\n  }\n\n  static calculateSessionKey(ofTokens: { refreshToken: string | null, accessToken?: string | null }): string {\n    if (ofTokens.refreshToken) {\n      return `refresh-${ofTokens.refreshToken}`;\n    } else if (ofTokens.accessToken) {\n      return `access-${ofTokens.accessToken}`;\n    } else {\n      return \"not-logged-in\";\n    }\n  }\n\n  isKnownToBeInvalid() {\n    return this._knownToBeInvalid.get();\n  }\n\n  /**\n   * Marks the session object as invalid, meaning that the refresh and access tokens can no longer be used.\n   */\n  markInvalid() {\n    this._accessToken.set(null);\n    this._knownToBeInvalid.set(true);\n  }\n\n  onInvalidate(callback: () => void): { unsubscribe: () => void } {\n    return this._knownToBeInvalid.onChange(() => callback());\n  }\n\n  /**\n   * Returns the access token if it is found in the cache and not expired yet, or null otherwise. Never fetches new tokens.\n   */\n  getAccessTokenIfNotExpiredYet(minMillisUntilExpiration: number): AccessToken | null {\n    if (minMillisUntilExpiration > 60_000) {\n      throw new Error(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short to be used for more than 60s`);\n    }\n\n    const accessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();\n    if (!accessToken || accessToken.expiresInMillis < minMillisUntilExpiration) return null;\n    return accessToken;\n  }\n\n  /**\n   * Returns the access token if it is found in the cache, fetching it otherwise.\n   *\n   * This is usually the function you want to call to get an access token. Either set `minMillisUntilExpiration` to a reasonable value, or catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).\n   *\n   * @returns null if the session is known to be invalid, cached tokens if they exist in the cache and the access token hasn't expired yet (the refresh token might still be invalid), or new tokens otherwise.\n   */\n  async getOrFetchLikelyValidTokens(minMillisUntilExpiration: number): Promise<{ accessToken: AccessToken, refreshToken: RefreshToken | null } | null> {\n    const accessToken = this.getAccessTokenIfNotExpiredYet(minMillisUntilExpiration);\n    if (!accessToken) {\n      const newTokens = await this.fetchNewTokens();\n      const expiresInMillis = newTokens?.accessToken.expiresInMillis;\n      if (expiresInMillis && expiresInMillis < minMillisUntilExpiration) {\n        throw new StackAssertionError(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short when they're generated (${expiresInMillis}ms)`);\n      }\n      return newTokens;\n    }\n    return { accessToken, refreshToken: this._refreshToken };\n  }\n\n  /**\n   * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.\n   *\n   * The newly generated tokens are short-lived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.\n   *\n   * In most cases, you should prefer `getOrFetchLikelyValidTokens`.\n   *\n   * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).\n   */\n  async fetchNewTokens(): Promise<{ accessToken: AccessToken, refreshToken: RefreshToken | null } | null> {\n    const accessToken = await this._getNewlyFetchedAccessToken();\n    return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;\n  }\n\n  markAccessTokenExpired(accessToken: AccessToken) {\n    // TODO we don't need this anymore, since we now check the expiry by ourselves\n    if (this._accessToken.get() === accessToken) {\n      this._accessToken.set(null);\n    }\n  }\n\n  /**\n   * 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.\n   */\n  onAccessTokenChange(callback: (newAccessToken: AccessToken | null) => void): { unsubscribe: () => void } {\n    return this._accessToken.onChange(callback);\n  }\n\n  /**\n   * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.\n   */\n  private _getPotentiallyInvalidAccessTokenIfAvailable(): AccessToken | null {\n    if (!this._refreshToken) return null;\n    if (this.isKnownToBeInvalid()) return null;\n\n    const accessToken = this._accessToken.get();\n    if (accessToken && !accessToken.isExpired()) return accessToken;\n\n    return null;\n  }\n\n  /**\n   * You should prefer `_getOrFetchPotentiallyInvalidAccessToken` in almost all cases.\n   *\n   * @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.\n   */\n  private async _getNewlyFetchedAccessToken(): Promise<AccessToken | null> {\n    if (!this._refreshToken) return null;\n    if (this._knownToBeInvalid.get()) return null;\n\n    if (!this._refreshPromise) {\n      this._refreshAndSetRefreshPromise(this._refreshToken);\n    }\n    return await this._refreshPromise;\n  }\n\n  private _refreshAndSetRefreshPromise(refreshToken: RefreshToken) {\n    let refreshPromise: Promise<AccessToken | null> = this._options.refreshAccessTokenCallback(refreshToken).then((accessToken) => {\n      if (refreshPromise === this._refreshPromise) {\n        this._refreshPromise = null;\n        this._accessToken.set(accessToken);\n        if (!accessToken) {\n          this.markInvalid();\n        }\n      }\n      return accessToken;\n    });\n    this._refreshPromise = refreshPromise;\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/sessions.ts"],"sourcesContent":["import * as jose from 'jose';\nimport { InferType } from 'yup';\nimport { accessTokenPayloadSchema } from './schema-fields';\nimport { StackAssertionError, throwErr } from \"./utils/errors\";\nimport { runAsynchronously, wait } from './utils/promises';\nimport { Store } from \"./utils/stores\";\n\n\nexport type AccessTokenPayload = InferType<typeof accessTokenPayloadSchema>;\n\nfunction decodeAccessTokenIfValid(token: string): AccessTokenPayload | null {\n  try {\n    const payload = jose.decodeJwt(token);\n    return accessTokenPayloadSchema.validateSync(payload);\n  } catch (e) {\n    return null;\n  }\n}\n\nexport class AccessToken {\n  static createIfValid(token: string): AccessToken | null {\n    const payload = decodeAccessTokenIfValid(token);\n    if (!payload) return null;\n    return new AccessToken(token);\n  }\n\n  private constructor(\n    public readonly token: string,\n  ) {\n    if (token === \"undefined\") {\n      throw new StackAssertionError(\"Access token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!\");\n    }\n  }\n\n  get payload() {\n    return decodeAccessTokenIfValid(this.token) ?? throwErr(\"Invalid access token in payload (should've been validated in createIfValid)\", { token: this.token });\n  }\n\n  get expiresAt(): Date {\n    const { exp } = this.payload;\n    if (exp === undefined) return new Date(8640000000000000);  // max date value\n    return new Date(exp * 1000);\n  }\n\n  get issuedAt(): Date {\n    const { iat } = this.payload;\n    return new Date(iat * 1000);\n  }\n\n  /**\n   * @returns The number of milliseconds until the access token expires, or 0 if it has already expired.\n   */\n  get expiresInMillis(): number {\n    return Math.max(0, this.expiresAt.getTime() - Date.now());\n  }\n\n  get issuedMillisAgo(): number {\n    return Math.max(0, Date.now() - this.issuedAt.getTime());\n  }\n\n  isExpired(): boolean {\n    return this.expiresInMillis <= 0;\n  }\n}\n\nexport class RefreshToken {\n  constructor(\n    public readonly token: string,\n  ) {\n    if (token === \"undefined\") {\n      throw new StackAssertionError(\"Refresh token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!\");\n    }\n  }\n}\n\n/**\n * An InternalSession represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.\n *\n * A session never changes which user or session it belongs to, but the tokens in it may change over time.\n */\nexport class InternalSession {\n  /**\n  * 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.\n  *\n  * 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.\n  *\n  * This is useful for caching and indexing sessions.\n  */\n  public readonly sessionKey: string;\n\n  /**\n   * An access token that is not known to be invalid (ie. may be valid, but may have expired).\n   */\n  private _accessToken: Store<AccessToken | null>;\n  private readonly _refreshToken: RefreshToken | null;\n\n  /**\n   * Whether the session as a whole is known to be invalid (ie. both access and refresh tokens are invalid). Used as a cache to avoid making multiple requests to the server (sessions never go back to being valid after being invalidated).\n   *\n   * It is possible for the access token to be invalid but the refresh token to be valid, in which case the session is\n   * still valid (just needs a refresh). It is also possible for the access token to be valid but the refresh token to\n   * be invalid, in which case the session is also valid (eg. if the refresh token is null because the user only passed\n   * in an access token, eg. in a server-side request handler).\n   */\n  private _knownToBeInvalid = new Store<boolean>(false);\n\n  private _refreshPromise: Promise<AccessToken | null> | null = null;\n\n  constructor(private readonly _options: {\n    refreshAccessTokenCallback(refreshToken: RefreshToken): Promise<AccessToken | null>,\n    refreshToken: string | null,\n    accessToken?: string | null,\n  }) {\n    this._accessToken = new Store(_options.accessToken ? AccessToken.createIfValid(_options.accessToken) : null);\n    this._refreshToken = _options.refreshToken ? new RefreshToken(_options.refreshToken) : null;\n    if (_options.accessToken === null && _options.refreshToken === null) {\n      // this session is already invalid\n      this._knownToBeInvalid.set(true);\n    }\n    this.sessionKey = InternalSession.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });\n  }\n\n  static calculateSessionKey(ofTokens: { refreshToken: string | null, accessToken?: string | null }): string {\n    if (ofTokens.refreshToken) {\n      return `refresh-${ofTokens.refreshToken}`;\n    } else if (ofTokens.accessToken) {\n      return `access-${ofTokens.accessToken}`;\n    } else {\n      return \"not-logged-in\";\n    }\n  }\n\n  isKnownToBeInvalid() {\n    return this._knownToBeInvalid.get();\n  }\n\n  /**\n   * Marks the session object as invalid, meaning that the refresh and access tokens can no longer be used. There is no\n   * way out of this state, and the session object will never return valid tokens again.\n   */\n  markInvalid() {\n    this._accessToken.set(null);\n    this._knownToBeInvalid.set(true);\n  }\n\n  onInvalidate(callback: () => void): { unsubscribe: () => void } {\n    return this._knownToBeInvalid.onChange(() => callback());\n  }\n\n  getRefreshToken(): RefreshToken | null {\n    if (this.isKnownToBeInvalid()) return null;\n    return this._refreshToken;\n  }\n\n  /**\n   * Returns the access token if it is found in the cache and not expired yet, or null otherwise. Never fetches new tokens.\n   */\n  getAccessTokenIfNotExpiredYet(minMillisUntilExpiration: number, maxMillisSinceIssued: number | null): AccessToken | null {\n    if (minMillisUntilExpiration > 45_000) {\n      throw new Error(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short to be used for more than 45s`);\n    }\n    if (maxMillisSinceIssued !== null && maxMillisSinceIssued < 15_000) {\n      throw new Error(`Required access token issuance ${maxMillisSinceIssued}ms is too short; assume that access token generation can take at least 15s`);\n    }\n\n    const accessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();\n    if (!accessToken || accessToken.expiresInMillis < minMillisUntilExpiration) return null;\n    if (maxMillisSinceIssued !== null && accessToken.issuedMillisAgo > maxMillisSinceIssued) return null;\n    return accessToken;\n  }\n\n  /**\n   * Returns the access token if it is found in the cache, fetching it otherwise.\n   *\n   * This is usually the function you want to call to get an access token. Either set `minMillisUntilExpiration` to a reasonable value, or catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).\n   *\n   * @returns null if the session is known to be invalid, cached tokens if they exist in the cache and the access token hasn't expired yet (the refresh token might still be invalid), or new tokens otherwise.\n   */\n  async getOrFetchLikelyValidTokens(minMillisUntilExpiration: number, maxMillisSinceIssued: number | null): Promise<{ accessToken: AccessToken, refreshToken: RefreshToken | null } | null> {\n    // fast path to save a roundtrip to the server if the session is known to be invalid\n    if (this.isKnownToBeInvalid()) return null;\n\n    const accessToken = this.getAccessTokenIfNotExpiredYet(minMillisUntilExpiration, maxMillisSinceIssued);\n    if (!accessToken) {\n      const newTokens = await this.fetchNewTokens();\n      const expiresInMillis = newTokens?.accessToken.expiresInMillis;\n      const issuedMillisAgo = newTokens?.accessToken.issuedMillisAgo;\n      if (expiresInMillis && expiresInMillis < minMillisUntilExpiration) {\n        throw new StackAssertionError(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short when they're generated (${expiresInMillis}ms)`);\n      }\n      if (maxMillisSinceIssued !== null && issuedMillisAgo && issuedMillisAgo > maxMillisSinceIssued) {\n        throw new StackAssertionError(`Required access token issuance ${maxMillisSinceIssued}ms is too short; access token issuance is too slow (${issuedMillisAgo}ms)`);\n      }\n      return newTokens;\n    }\n    return { accessToken, refreshToken: this.getRefreshToken() };\n  }\n\n  /**\n   * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.\n   *\n   * The newly generated tokens are short-lived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.\n   *\n   * In most cases, you should prefer `getOrFetchLikelyValidTokens`.\n   *\n   * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).\n   */\n  async fetchNewTokens(): Promise<{ accessToken: AccessToken, refreshToken: RefreshToken | null } | null> {\n    const accessToken = await this._getNewlyFetchedAccessToken();\n    return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;\n  }\n\n  /**\n   * Manually mark the access token as expired, even if the date on its payload may still be valid.\n   *\n   * You don't usually have to call this function anymore, but you may want to call suggestAccessTokenExpired\n   * to hint that the access token should be refreshed as its data may have changed, if possible.\n   */\n  markAccessTokenExpired(accessToken?: AccessToken) {\n    if (!accessToken || this._accessToken.get()?.token === accessToken.token) {\n      this._accessToken.set(null);\n    }\n  }\n\n  /**\n   * Strongly suggests that the access token should be refreshed as its data may have changed, although it's up to this\n   * implementation to decide whether or when the access token will be refreshed.\n   *\n   * This is particularly useful when the data associated with the access token may have changed for example due to an\n   * update to the user's profile.\n   *\n   * The current implementation marks the access token as expired if and only if a refresh token is available (regardless of\n   * whether the refresh token is actually valid or not), although this is not a guarantee and subject to change.\n   *\n   * If you need a stronger guarantee of revoking an access token, use markAccessTokenExpired instead.\n   */\n  suggestAccessTokenExpired(): void {\n    if (this._refreshToken) {\n      this.markAccessTokenExpired();\n    }\n  }\n\n  startRefreshingAccessToken(minMillisUntilExpiration: number, maxMillisSinceIssued: number | null): { unsubscribe: () => void } {\n    let canceled = false;\n    runAsynchronously(async () => {\n      while (!canceled) {\n        const tokens = await this.getOrFetchLikelyValidTokens(minMillisUntilExpiration, maxMillisSinceIssued);\n        if (!tokens) return;  // session is invalid, stop refreshing\n        const nextRefreshIn = Math.min(\n          tokens.accessToken.expiresInMillis - minMillisUntilExpiration,\n          (maxMillisSinceIssued ?? Infinity) - tokens.accessToken.issuedMillisAgo,\n        );\n        await wait(Math.max(1, nextRefreshIn));\n      }\n    });\n    return {\n      unsubscribe: () => {\n        canceled = true;\n      },\n    };\n  }\n\n  /**\n   * 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.\n   */\n  onAccessTokenChange(callback: (newAccessToken: AccessToken | null) => void): { unsubscribe: () => void } {\n    return this._accessToken.onChange(callback);\n  }\n\n  /**\n   * @returns An access token, which may be expired or expire soon, or null if it is known to be invalid.\n   */\n  private _getPotentiallyInvalidAccessTokenIfAvailable(): AccessToken | null {\n    if (!this._refreshToken) return null;\n    if (this.isKnownToBeInvalid()) return null;\n\n    const accessToken = this._accessToken.get();\n    if (accessToken && !accessToken.isExpired()) return accessToken;\n\n    return null;\n  }\n\n  /**\n   * You should prefer `_getOrFetchPotentiallyInvalidAccessToken` in almost all cases.\n   *\n   * @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.\n   */\n  private async _getNewlyFetchedAccessToken(): Promise<AccessToken | null> {\n    if (!this._refreshToken) return null;\n    if (this._knownToBeInvalid.get()) return null;\n\n    if (!this._refreshPromise) {\n      this._refreshAndSetRefreshPromise(this._refreshToken);\n    }\n    return await this._refreshPromise;\n  }\n\n  private _refreshAndSetRefreshPromise(refreshToken: RefreshToken) {\n    let refreshPromise: Promise<AccessToken | null> = this._options.refreshAccessTokenCallback(refreshToken).then((accessToken) => {\n      if (refreshPromise === this._refreshPromise) {\n        this._refreshPromise = null;\n        this._accessToken.set(accessToken);\n        if (!accessToken) {\n          this.markInvalid();\n        }\n      }\n      return accessToken;\n    });\n    this._refreshPromise = refreshPromise;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/esm/utils/env.js

@@ -1,5 +1,5 @@
 // src/utils/env.tsx
-import { throwErr } from "./errors.js";
+import { StackAssertionError, throwErr } from "./errors.js";
 import { deindent } from "./strings.js";
 function isBrowserLike() {
   return typeof window !== "undefined" && typeof document !== "undefined" && typeof document.createElement !== "undefined";
@@ -34,7 +34,7 @@ function getEnvVariable(name, defaultValue) {
       if (value) break;
     }
   }
-  if (value === void 0) {
+  if (!value) {
     if (defaultValue !== void 0) {
       value = defaultValue;
     } else {
@@ -43,6 +43,16 @@ function getEnvVariable(name, defaultValue) {
   }
   return value;
 }
+function getEnvBoolean(name) {
+  const value = getEnvVariable(name, "false");
+  if (value === "true") {
+    return true;
+  } else if (value === "false") {
+    return false;
+  } else {
+    throw new StackAssertionError(`Environment variable ${name} must be either "true" or "false": found ${JSON.stringify(value)}`);
+  }
+}
 function getNextRuntime() {
   return process.env.NEXT_RUNTIME || throwErr("Missing environment variable: NEXT_RUNTIME");
 }
@@ -50,6 +60,7 @@ function getNodeEnvironment() {
   return getEnvVariable("NODE_ENV", "");
 }
 export {
+  getEnvBoolean,
   getEnvVariable,
   getNextRuntime,
   getNodeEnvironment,

package/dist/esm/utils/env.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/env.tsx"],"sourcesContent":["import { throwErr } from \"./errors\";\nimport { deindent } from \"./strings\";\n\nexport function isBrowserLike() {\n  return typeof window !== \"undefined\" && typeof document !== \"undefined\" && typeof document.createElement !== \"undefined\";\n}\n\n// newName: oldName\nconst ENV_VAR_RENAME: Record<string, string[]> = {\n  NEXT_PUBLIC_STACK_API_URL: ['STACK_BASE_URL', 'NEXT_PUBLIC_STACK_URL'],\n};\n\n/**\n * Returns the environment variable with the given name, returning the default (if given) or throwing an error (otherwise) if it's undefined or the empty string.\n */\nexport function getEnvVariable(name: string, defaultValue?: string | undefined): string {\n  if (isBrowserLike()) {\n    throw new Error(deindent`\n      Can't use getEnvVariable on the client because Next.js transpiles expressions of the kind process.env.XYZ at build-time on the client.\n    \n      Use process.env.XYZ directly instead.\n    `);\n  }\n  if (name === \"NEXT_RUNTIME\") {\n    throw new Error(deindent`\n      Can't use getEnvVariable to access the NEXT_RUNTIME environment variable because it's compiled into the client bundle.\n    \n      Use getNextRuntime() instead.\n    `);\n  }\n\n  // throw error if the old name is used as the retrieve key\n  for (const [newName, oldNames] of Object.entries(ENV_VAR_RENAME)) {\n    if (oldNames.includes(name)) {\n      throwErr(`Environment variable ${name} has been renamed to ${newName}. Please update your configuration to use the new name.`);\n    }\n  }\n\n  let value = process.env[name];\n\n  // check the key under the old name if the new name is not found\n  if (!value && ENV_VAR_RENAME[name] as any) {\n    for (const oldName of ENV_VAR_RENAME[name]) {\n      value = process.env[oldName];\n      if (value) break;\n    }\n  }\n\n  if (value === undefined) {\n    if (defaultValue !== undefined) {\n      value = defaultValue;\n    } else {\n      throwErr(`Missing environment variable: ${name}`);\n    }\n  }\n\n  return value;\n}\n\nexport function getNextRuntime() {\n  // This variable is compiled into the client bundle, so we can't use getEnvVariable here.\n  return process.env.NEXT_RUNTIME || throwErr(\"Missing environment variable: NEXT_RUNTIME\");\n}\n\nexport function getNodeEnvironment() {\n  return getEnvVariable(\"NODE_ENV\", \"\");\n}\n"],"mappings":";AAAA,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AAElB,SAAS,gBAAgB;AAC9B,SAAO,OAAO,WAAW,eAAe,OAAO,aAAa,eAAe,OAAO,SAAS,kBAAkB;AAC/G;AAGA,IAAM,iBAA2C;AAAA,EAC/C,2BAA2B,CAAC,kBAAkB,uBAAuB;AACvE;AAKO,SAAS,eAAe,MAAc,cAA2C;AACtF,MAAI,cAAc,GAAG;AACnB,UAAM,IAAI,MAAM;AAAA;AAAA;AAAA;AAAA,KAIf;AAAA,EACH;AACA,MAAI,SAAS,gBAAgB;AAC3B,UAAM,IAAI,MAAM;AAAA;AAAA;AAAA;AAAA,KAIf;AAAA,EACH;AAGA,aAAW,CAAC,SAAS,QAAQ,KAAK,OAAO,QAAQ,cAAc,GAAG;AAChE,QAAI,SAAS,SAAS,IAAI,GAAG;AAC3B,eAAS,wBAAwB,IAAI,wBAAwB,OAAO,yDAAyD;AAAA,IAC/H;AAAA,EACF;AAEA,MAAI,QAAQ,QAAQ,IAAI,IAAI;AAG5B,MAAI,CAAC,SAAS,eAAe,IAAI,GAAU;AACzC,eAAW,WAAW,eAAe,IAAI,GAAG;AAC1C,cAAQ,QAAQ,IAAI,OAAO;AAC3B,UAAI,MAAO;AAAA,IACb;AAAA,EACF;AAEA,MAAI,UAAU,QAAW;AACvB,QAAI,iBAAiB,QAAW;AAC9B,cAAQ;AAAA,IACV,OAAO;AACL,eAAS,iCAAiC,IAAI,EAAE;AAAA,IAClD;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,iBAAiB;AAE/B,SAAO,QAAQ,IAAI,gBAAgB,SAAS,4CAA4C;AAC1F;AAEO,SAAS,qBAAqB;AACnC,SAAO,eAAe,YAAY,EAAE;AACtC;","names":[]}
+{"version":3,"sources":["../../../src/utils/env.tsx"],"sourcesContent":["import { StackAssertionError, throwErr } from \"./errors\";\nimport { deindent } from \"./strings\";\n\nexport function isBrowserLike() {\n  return typeof window !== \"undefined\" && typeof document !== \"undefined\" && typeof document.createElement !== \"undefined\";\n}\n\n// newName: oldName\nconst ENV_VAR_RENAME: Record<string, string[]> = {\n  NEXT_PUBLIC_STACK_API_URL: ['STACK_BASE_URL', 'NEXT_PUBLIC_STACK_URL'],\n};\n\n/**\n * Returns the environment variable with the given name, returning the default (if given) or throwing an error (otherwise) if it's undefined or the empty string.\n */\nexport function getEnvVariable(name: string, defaultValue?: string | undefined): string {\n  if (isBrowserLike()) {\n    throw new Error(deindent`\n      Can't use getEnvVariable on the client because Next.js transpiles expressions of the kind process.env.XYZ at build-time on the client.\n    \n      Use process.env.XYZ directly instead.\n    `);\n  }\n  if (name === \"NEXT_RUNTIME\") {\n    throw new Error(deindent`\n      Can't use getEnvVariable to access the NEXT_RUNTIME environment variable because it's compiled into the client bundle.\n    \n      Use getNextRuntime() instead.\n    `);\n  }\n\n  // throw error if the old name is used as the retrieve key\n  for (const [newName, oldNames] of Object.entries(ENV_VAR_RENAME)) {\n    if (oldNames.includes(name)) {\n      throwErr(`Environment variable ${name} has been renamed to ${newName}. Please update your configuration to use the new name.`);\n    }\n  }\n\n  let value = process.env[name];\n\n  // check the key under the old name if the new name is not found\n  if (!value && ENV_VAR_RENAME[name] as any) {\n    for (const oldName of ENV_VAR_RENAME[name]) {\n      value = process.env[oldName];\n      if (value) break;\n    }\n  }\n\n  if (!value) {\n    if (defaultValue !== undefined) {\n      value = defaultValue;\n    } else {\n      throwErr(`Missing environment variable: ${name}`);\n    }\n  }\n\n  return value;\n}\n\nexport function getEnvBoolean(name: string): boolean {\n  const value = getEnvVariable(name, \"false\");\n  if (value === \"true\") {\n    return true;\n  } else if (value === \"false\") {\n    return false;\n  } else {\n    throw new StackAssertionError(`Environment variable ${name} must be either \"true\" or \"false\": found ${JSON.stringify(value)}`);\n  }\n}\n\nexport function getNextRuntime() {\n  // This variable is compiled into the client bundle, so we can't use getEnvVariable here.\n  return process.env.NEXT_RUNTIME || throwErr(\"Missing environment variable: NEXT_RUNTIME\");\n}\n\nexport function getNodeEnvironment() {\n  return getEnvVariable(\"NODE_ENV\", \"\");\n}\n"],"mappings":";AAAA,SAAS,qBAAqB,gBAAgB;AAC9C,SAAS,gBAAgB;AAElB,SAAS,gBAAgB;AAC9B,SAAO,OAAO,WAAW,eAAe,OAAO,aAAa,eAAe,OAAO,SAAS,kBAAkB;AAC/G;AAGA,IAAM,iBAA2C;AAAA,EAC/C,2BAA2B,CAAC,kBAAkB,uBAAuB;AACvE;AAKO,SAAS,eAAe,MAAc,cAA2C;AACtF,MAAI,cAAc,GAAG;AACnB,UAAM,IAAI,MAAM;AAAA;AAAA;AAAA;AAAA,KAIf;AAAA,EACH;AACA,MAAI,SAAS,gBAAgB;AAC3B,UAAM,IAAI,MAAM;AAAA;AAAA;AAAA;AAAA,KAIf;AAAA,EACH;AAGA,aAAW,CAAC,SAAS,QAAQ,KAAK,OAAO,QAAQ,cAAc,GAAG;AAChE,QAAI,SAAS,SAAS,IAAI,GAAG;AAC3B,eAAS,wBAAwB,IAAI,wBAAwB,OAAO,yDAAyD;AAAA,IAC/H;AAAA,EACF;AAEA,MAAI,QAAQ,QAAQ,IAAI,IAAI;AAG5B,MAAI,CAAC,SAAS,eAAe,IAAI,GAAU;AACzC,eAAW,WAAW,eAAe,IAAI,GAAG;AAC1C,cAAQ,QAAQ,IAAI,OAAO;AAC3B,UAAI,MAAO;AAAA,IACb;AAAA,EACF;AAEA,MAAI,CAAC,OAAO;AACV,QAAI,iBAAiB,QAAW;AAC9B,cAAQ;AAAA,IACV,OAAO;AACL,eAAS,iCAAiC,IAAI,EAAE;AAAA,IAClD;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,cAAc,MAAuB;AACnD,QAAM,QAAQ,eAAe,MAAM,OAAO;AAC1C,MAAI,UAAU,QAAQ;AACpB,WAAO;AAAA,EACT,WAAW,UAAU,SAAS;AAC5B,WAAO;AAAA,EACT,OAAO;AACL,UAAM,IAAI,oBAAoB,wBAAwB,IAAI,4CAA4C,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,EAC/H;AACF;AAEO,SAAS,iBAAiB;AAE/B,SAAO,QAAQ,IAAI,gBAAgB,SAAS,4CAA4C;AAC1F;AAEO,SAAS,qBAAqB;AACnC,SAAO,eAAe,YAAY,EAAE;AACtC;","names":[]}

package/dist/esm/utils/esbuild.js

@@ -2,36 +2,65 @@
 import * as esbuild from "esbuild-wasm/lib/browser.js";
 import { join } from "path";
 import { isBrowserLike } from "./env.js";
-import { StackAssertionError, throwErr } from "./errors.js";
+import { captureError, StackAssertionError, throwErr } from "./errors.js";
+import { ignoreUnhandledRejection, runAsynchronously } from "./promises.js";
 import { Result } from "./results.js";
 import { traceSpan, withTraceSpan } from "./telemetry.js";
-var esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
-var esbuildInitializePromise = null;
+import { createGlobalAsync } from "./globals.js";
 globalThis.self ??= globalThis;
+if (process.env.NODE_ENV === "development" && typeof process !== "undefined" && typeof process.exit === "function") {
+  runAsynchronously(async () => {
+    try {
+      await initializeEsbuild();
+    } catch (e) {
+      captureError("initialize-esbuild-in-dev", e);
+      globalThis.process?.exit?.(1);
+    }
+  });
+}
+var esbuildInitializePromise = null;
 function initializeEsbuild() {
-  if (!esbuildInitializePromise) {
+  const esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
+  if (esbuildInitializePromise == null) {
     esbuildInitializePromise = withTraceSpan("initializeEsbuild", async () => {
-      if (isBrowserLike()) {
-        await esbuild.initialize({
-          wasmURL: esbuildWasmUrl
-        });
-      } else {
-        const esbuildWasmResponse = await fetch(esbuildWasmUrl);
-        if (!esbuildWasmResponse.ok) {
-          throw new StackAssertionError(`Failed to fetch esbuild.wasm: ${esbuildWasmResponse.status} ${esbuildWasmResponse.statusText}: ${await esbuildWasmResponse.text()}`);
+      try {
+        let initOptions;
+        if (isBrowserLike()) {
+          initOptions = {
+            wasmURL: esbuildWasmUrl
+          };
+        } else {
+          const esbuildWasmModule = await createGlobalAsync("esbuildWasmModule", async () => {
+            const esbuildWasmResponse = await fetch(esbuildWasmUrl);
+            if (!esbuildWasmResponse.ok) {
+              throw new StackAssertionError(`Failed to fetch esbuild.wasm: ${esbuildWasmResponse.status} ${esbuildWasmResponse.statusText}: ${await esbuildWasmResponse.text()}`);
+            }
+            const esbuildWasm = await esbuildWasmResponse.arrayBuffer();
+            const esbuildWasmArray = new Uint8Array(esbuildWasm);
+            if (esbuildWasmArray[0] !== 0 || esbuildWasmArray[1] !== 97 || esbuildWasmArray[2] !== 115 || esbuildWasmArray[3] !== 109) {
+              throw new StackAssertionError(`Invalid esbuild.wasm file: ${new TextDecoder().decode(esbuildWasmArray)}`);
+            }
+            return new WebAssembly.Module(esbuildWasm);
+          });
+          initOptions = {
+            wasmModule: esbuildWasmModule,
+            worker: false
+          };
         }
-        const esbuildWasm = await esbuildWasmResponse.arrayBuffer();
-        const esbuildWasmArray = new Uint8Array(esbuildWasm);
-        if (esbuildWasmArray[0] !== 0 || esbuildWasmArray[1] !== 97 || esbuildWasmArray[2] !== 115 || esbuildWasmArray[3] !== 109) {
-          throw new StackAssertionError(`Invalid esbuild.wasm file: ${new TextDecoder().decode(esbuildWasmArray)}`);
+        try {
+          await esbuild.initialize(initOptions);
+        } catch (e) {
+          if (e instanceof Error && e.message === 'Cannot call "initialize" more than once') {
+          } else {
+            throw e;
+          }
         }
-        const esbuildWasmModule = new WebAssembly.Module(esbuildWasm);
-        await esbuild.initialize({
-          wasmModule: esbuildWasmModule,
-          worker: false
-        });
+      } catch (e) {
+        esbuildInitializePromise = null;
+        throw new StackAssertionError("Failed to initialize ESBuild", { cause: e });
       }
     })();
+    ignoreUnhandledRejection(esbuildInitializePromise);
   }
   return esbuildInitializePromise;
 }

package/dist/esm/utils/esbuild.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/esbuild.tsx"],"sourcesContent":["import * as esbuild from 'esbuild-wasm/lib/browser.js';\nimport { join } from 'path';\nimport { isBrowserLike } from './env';\nimport { StackAssertionError, throwErr } from \"./errors\";\nimport { Result } from \"./results\";\nimport { traceSpan, withTraceSpan } from './telemetry';\n\nconst esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;\n\nlet esbuildInitializePromise: Promise<void> | null = null;\n// esbuild requires self property to be set, and it is not set by default in nodejs\n(globalThis.self as any) ??= globalThis as any;\n\nexport function initializeEsbuild(): Promise<void> {\n  if (!esbuildInitializePromise) {\n    esbuildInitializePromise = withTraceSpan('initializeEsbuild', async () => {\n      if (isBrowserLike()) {\n        await esbuild.initialize({\n          wasmURL: esbuildWasmUrl,\n        });\n      } else {\n        const esbuildWasmResponse = await fetch(esbuildWasmUrl);\n        if (!esbuildWasmResponse.ok) {\n          throw new StackAssertionError(`Failed to fetch esbuild.wasm: ${esbuildWasmResponse.status} ${esbuildWasmResponse.statusText}: ${await esbuildWasmResponse.text()}`);\n        }\n        const esbuildWasm = await esbuildWasmResponse.arrayBuffer();\n        const esbuildWasmArray = new Uint8Array(esbuildWasm);\n        if (esbuildWasmArray[0] !== 0x00 || esbuildWasmArray[1] !== 0x61 || esbuildWasmArray[2] !== 0x73 || esbuildWasmArray[3] !== 0x6d) {\n          throw new StackAssertionError(`Invalid esbuild.wasm file: ${new TextDecoder().decode(esbuildWasmArray)}`);\n        }\n        const esbuildWasmModule = new WebAssembly.Module(esbuildWasm);\n        await esbuild.initialize({\n          wasmModule: esbuildWasmModule,\n          worker: false,\n        });\n      }\n    })();\n  }\n\n  return esbuildInitializePromise;\n}\n\nexport async function bundleJavaScript(sourceFiles: Record<string, string> & { '/entry.js': string }, options: {\n  format?: 'iife' | 'esm' | 'cjs',\n  externalPackages?: Record<string, string>,\n  keepAsImports?: string[],\n  sourcemap?: false | 'inline',\n  allowHttpImports?: boolean,\n} = {}): Promise<Result<string, string>> {\n  await initializeEsbuild();\n\n  const sourceFilesMap = new Map(Object.entries(sourceFiles));\n  const externalPackagesMap = new Map(Object.entries(options.externalPackages ?? {}));\n  const keepAsImports = options.keepAsImports ?? [];\n\n  const httpImportCache = new Map<string, { contents: string, loader: esbuild.Loader, resolveDir: string }>();\n\n  const extToLoader: Map<string, esbuild.Loader> = new Map([\n    ['tsx', 'tsx'],\n    ['ts', 'ts'],\n    ['js', 'js'],\n    ['jsx', 'jsx'],\n    ['json', 'json'],\n    ['css', 'css'],\n  ]);\n  let result;\n  try {\n    result = await traceSpan('bundleJavaScript', async () => await esbuild.build({\n      entryPoints: ['/entry.js'],\n      bundle: true,\n      write: false,\n      format: options.format ?? 'iife',\n      platform: 'browser',\n      target: 'es2015',\n      jsx: 'automatic',\n      sourcemap: options.sourcemap ?? 'inline',\n      external: keepAsImports,\n      plugins: [\n        ...options.allowHttpImports ? [{\n          name: \"esm-sh-only\",\n          setup(build: esbuild.PluginBuild) {\n            // Handle absolute URLs and relative imports from esm.sh modules.\n            build.onResolve({ filter: /.*/ }, (args) => {\n              // Only touch absolute http(s) specifiers or children of our own namespace\n              const isHttp = args.path.startsWith(\"http://\") || args.path.startsWith(\"https://\");\n              const fromEsmNs = args.namespace === \"esm-sh\";\n\n              if (!isHttp && !fromEsmNs) return null; // Let other plugins handle bare/relative/local\n\n              // Resolve relative URLs inside esm.sh-fetched modules\n              const url = new URL(args.path, fromEsmNs ? args.importer : undefined);\n\n              if (url.protocol !== \"https:\" || url.host !== \"esm.sh\") {\n                throw new Error(`Blocked non-esm.sh URL import: ${url.href}`);\n              }\n\n              return { path: url.href, namespace: \"esm-sh\" };\n            });\n\n            build.onLoad({ filter: /.*/, namespace: \"esm-sh\" }, async (args) => {\n              if (httpImportCache.has(args.path)) return httpImportCache.get(args.path)!;\n\n              const res = await fetch(args.path, { redirect: \"follow\" });\n              if (!res.ok) throw new Error(`Fetch ${res.status} ${res.statusText} for ${args.path}`);\n              const finalUrl = new URL(res.url);\n              // Defensive: follow shouldn’t leave esm.sh, but re-check.\n              if (finalUrl.host !== \"esm.sh\") {\n                throw new Error(`Redirect escaped esm.sh: ${finalUrl.href}`);\n              }\n\n              const ct = (res.headers.get(\"content-type\") || \"\").toLowerCase();\n              let loader: esbuild.Loader =\n                ct.includes(\"css\") ? \"css\" :\n                ct.includes(\"json\") ? \"json\" :\n                ct.includes(\"typescript\") ? \"ts\" :\n                ct.includes(\"jsx\") ? \"jsx\" :\n                ct.includes(\"tsx\") ? \"tsx\" :\n                  \"js\";\n\n              // Fallback by extension (esm.sh sometimes omits CT)\n              const p = finalUrl.pathname;\n              if (p.endsWith(\".css\")) loader = \"css\";\n              else if (p.endsWith(\".json\")) loader = \"json\";\n              else if (p.endsWith(\".ts\")) loader = \"ts\";\n              else if (p.endsWith(\".tsx\")) loader = \"tsx\";\n              else if (p.endsWith(\".jsx\")) loader = \"jsx\";\n\n              const contents = await res.text();\n              const result = {\n                contents,\n                loader,\n                // Ensures relative imports inside that module resolve against the file’s URL\n                resolveDir: new URL(\".\", finalUrl.href).toString(),\n                watchFiles: [finalUrl.href],\n              };\n              httpImportCache.set(args.path, result);\n              return result;\n            });\n          },\n        } as esbuild.Plugin] : [],\n        {\n          name: 'replace-packages-with-globals',\n          setup(build) {\n            build.onResolve({ filter: /.*/ }, args => {\n              // Skip packages that should remain external (not be shimmed)\n              if (keepAsImports.includes(args.path)) {\n                return undefined;\n              }\n              if (externalPackagesMap.has(args.path)) {\n                return { path: args.path, namespace: 'package-shim' };\n              }\n              return undefined;\n            });\n\n            build.onLoad({ filter: /.*/, namespace: 'package-shim' }, (args) => {\n              const contents = externalPackagesMap.get(args.path);\n              if (contents == null) throw new StackAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);\n\n              return { contents, loader: 'ts' };\n            });\n          },\n        },\n        {\n          name: 'virtual-fs',\n          setup(build) {\n            build.onResolve({ filter: /.*/ }, args => {\n              const absolutePath = join(\"/\", args.path);\n              if (sourceFilesMap.has(absolutePath)) {\n                return { path: absolutePath, namespace: 'virtual' };\n              }\n              return undefined;\n            });\n\n            /* 2️⃣  Load the module from the map */\n            build.onLoad({ filter: /.*/, namespace: 'virtual' }, args => {\n              const contents = sourceFilesMap.get(args.path);\n              if (contents == null) throw new StackAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);\n\n              const ext = args.path.split('.').pop() ?? '';\n              const loader = extToLoader.get(ext) ?? throwErr(`esbuild requested file ${args.path} with unknown extension ${ext}`);\n\n              return { contents, loader };\n            });\n          },\n        },\n      ],\n    }));\n  } catch (e) {\n    if (e instanceof Error && e.message.startsWith(\"Build failed with \")) {\n      return Result.error(e.message);\n    }\n    throw e;\n  }\n\n  if (result.errors.length > 0) {\n    return Result.error(result.errors.map(e => e.text).join('\\n'));\n  }\n\n  if (result.outputFiles.length > 0) {\n    return Result.ok(result.outputFiles[0].text);\n  }\n  return throwErr(\"No output generated??\");\n}\n"],"mappings":"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","names":["build","result"]}
+{"version":3,"sources":["../../../src/utils/esbuild.tsx"],"sourcesContent":["import * as esbuild from 'esbuild-wasm/lib/browser.js';\nimport { join } from 'path';\nimport { isBrowserLike } from './env';\nimport { captureError, StackAssertionError, throwErr } from \"./errors\";\nimport { ignoreUnhandledRejection, runAsynchronously } from './promises';\nimport { Result } from \"./results\";\nimport { traceSpan, withTraceSpan } from './telemetry';\nimport { createGlobalAsync } from './globals';\n\n\n// esbuild requires self property to be set, and it is not set by default in nodejs\n(globalThis.self as any) ??= globalThis as any;\n\n\nif (process.env.NODE_ENV === 'development' && typeof process !== \"undefined\" && typeof process.exit === \"function\") {\n  // On development Node.js servers, initialize ESBuild as soon as the module is imported so we have to wait less on the first request\n  runAsynchronously(async () => {\n    try {\n      await initializeEsbuild();\n    } catch (e) {\n      captureError(\"initialize-esbuild-in-dev\", e);\n      (globalThis as any).process?.exit?.(1);\n    }\n  });\n}\n\nlet esbuildInitializePromise: Promise<void> | null = null;\n\nexport function initializeEsbuild(): Promise<void> {\n  const esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;\n  if (esbuildInitializePromise == null) {\n    esbuildInitializePromise = withTraceSpan('initializeEsbuild', async () => {\n      try {\n        let initOptions;\n        if (isBrowserLike()) {\n          initOptions = {\n            wasmURL: esbuildWasmUrl,\n          };\n        } else {\n          const esbuildWasmModule = await createGlobalAsync('esbuildWasmModule', async () => {\n            const esbuildWasmResponse = await fetch(esbuildWasmUrl);\n            if (!esbuildWasmResponse.ok) {\n              throw new StackAssertionError(`Failed to fetch esbuild.wasm: ${esbuildWasmResponse.status} ${esbuildWasmResponse.statusText}: ${await esbuildWasmResponse.text()}`);\n            }\n            const esbuildWasm = await esbuildWasmResponse.arrayBuffer();\n            const esbuildWasmArray = new Uint8Array(esbuildWasm);\n            if (esbuildWasmArray[0] !== 0x00 || esbuildWasmArray[1] !== 0x61 || esbuildWasmArray[2] !== 0x73 || esbuildWasmArray[3] !== 0x6d) {\n              throw new StackAssertionError(`Invalid esbuild.wasm file: ${new TextDecoder().decode(esbuildWasmArray)}`);\n            }\n            return new WebAssembly.Module(esbuildWasm);\n          });\n          initOptions = {\n            wasmModule: esbuildWasmModule,\n            worker: false,\n          };\n        }\n        try {\n          await esbuild.initialize(initOptions);\n        } catch (e) {\n          if (e instanceof Error && e.message === 'Cannot call \"initialize\" more than once') {\n            // this happens especially in local development, just ignore\n          } else {\n            throw e;\n          }\n        }\n      } catch (e) {\n        esbuildInitializePromise = null;\n        throw new StackAssertionError(\"Failed to initialize ESBuild\", { cause: e });\n      }\n    })();\n    ignoreUnhandledRejection(esbuildInitializePromise);\n  }\n\n  return esbuildInitializePromise;\n}\n\nexport async function bundleJavaScript(sourceFiles: Record<string, string> & { '/entry.js': string }, options: {\n  format?: 'iife' | 'esm' | 'cjs',\n  externalPackages?: Record<string, string>,\n  keepAsImports?: string[],\n  sourcemap?: false | 'inline',\n  allowHttpImports?: boolean,\n} = {}): Promise<Result<string, string>> {\n  await initializeEsbuild();\n\n  const sourceFilesMap = new Map(Object.entries(sourceFiles));\n  const externalPackagesMap = new Map(Object.entries(options.externalPackages ?? {}));\n  const keepAsImports = options.keepAsImports ?? [];\n\n  const httpImportCache = new Map<string, { contents: string, loader: esbuild.Loader, resolveDir: string }>();\n\n  const extToLoader: Map<string, esbuild.Loader> = new Map([\n    ['tsx', 'tsx'],\n    ['ts', 'ts'],\n    ['js', 'js'],\n    ['jsx', 'jsx'],\n    ['json', 'json'],\n    ['css', 'css'],\n  ]);\n  let result;\n  try {\n    result = await traceSpan('bundleJavaScript', async () => await esbuild.build({\n      entryPoints: ['/entry.js'],\n      bundle: true,\n      write: false,\n      format: options.format ?? 'iife',\n      platform: 'browser',\n      target: 'es2015',\n      jsx: 'automatic',\n      sourcemap: options.sourcemap ?? 'inline',\n      external: keepAsImports,\n      plugins: [\n        ...options.allowHttpImports ? [{\n          name: \"esm-sh-only\",\n          setup(build: esbuild.PluginBuild) {\n            // Handle absolute URLs and relative imports from esm.sh modules.\n            build.onResolve({ filter: /.*/ }, (args) => {\n              // Only touch absolute http(s) specifiers or children of our own namespace\n              const isHttp = args.path.startsWith(\"http://\") || args.path.startsWith(\"https://\");\n              const fromEsmNs = args.namespace === \"esm-sh\";\n\n              if (!isHttp && !fromEsmNs) return null; // Let other plugins handle bare/relative/local\n\n              // Resolve relative URLs inside esm.sh-fetched modules\n              const url = new URL(args.path, fromEsmNs ? args.importer : undefined);\n\n              if (url.protocol !== \"https:\" || url.host !== \"esm.sh\") {\n                throw new Error(`Blocked non-esm.sh URL import: ${url.href}`);\n              }\n\n              return { path: url.href, namespace: \"esm-sh\" };\n            });\n\n            build.onLoad({ filter: /.*/, namespace: \"esm-sh\" }, async (args) => {\n              if (httpImportCache.has(args.path)) return httpImportCache.get(args.path)!;\n\n              const res = await fetch(args.path, { redirect: \"follow\" });\n              if (!res.ok) throw new Error(`Fetch ${res.status} ${res.statusText} for ${args.path}`);\n              const finalUrl = new URL(res.url);\n              // Defensive: follow shouldn’t leave esm.sh, but re-check.\n              if (finalUrl.host !== \"esm.sh\") {\n                throw new Error(`Redirect escaped esm.sh: ${finalUrl.href}`);\n              }\n\n              const ct = (res.headers.get(\"content-type\") || \"\").toLowerCase();\n              let loader: esbuild.Loader =\n                ct.includes(\"css\") ? \"css\" :\n                ct.includes(\"json\") ? \"json\" :\n                ct.includes(\"typescript\") ? \"ts\" :\n                ct.includes(\"jsx\") ? \"jsx\" :\n                ct.includes(\"tsx\") ? \"tsx\" :\n                  \"js\";\n\n              // Fallback by extension (esm.sh sometimes omits CT)\n              const p = finalUrl.pathname;\n              if (p.endsWith(\".css\")) loader = \"css\";\n              else if (p.endsWith(\".json\")) loader = \"json\";\n              else if (p.endsWith(\".ts\")) loader = \"ts\";\n              else if (p.endsWith(\".tsx\")) loader = \"tsx\";\n              else if (p.endsWith(\".jsx\")) loader = \"jsx\";\n\n              const contents = await res.text();\n              const result = {\n                contents,\n                loader,\n                // Ensures relative imports inside that module resolve against the file’s URL\n                resolveDir: new URL(\".\", finalUrl.href).toString(),\n                watchFiles: [finalUrl.href],\n              };\n              httpImportCache.set(args.path, result);\n              return result;\n            });\n          },\n        } as esbuild.Plugin] : [],\n        {\n          name: 'replace-packages-with-globals',\n          setup(build) {\n            build.onResolve({ filter: /.*/ }, args => {\n              // Skip packages that should remain external (not be shimmed)\n              if (keepAsImports.includes(args.path)) {\n                return undefined;\n              }\n              if (externalPackagesMap.has(args.path)) {\n                return { path: args.path, namespace: 'package-shim' };\n              }\n              return undefined;\n            });\n\n            build.onLoad({ filter: /.*/, namespace: 'package-shim' }, (args) => {\n              const contents = externalPackagesMap.get(args.path);\n              if (contents == null) throw new StackAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);\n\n              return { contents, loader: 'ts' };\n            });\n          },\n        },\n        {\n          name: 'virtual-fs',\n          setup(build) {\n            build.onResolve({ filter: /.*/ }, args => {\n              const absolutePath = join(\"/\", args.path);\n              if (sourceFilesMap.has(absolutePath)) {\n                return { path: absolutePath, namespace: 'virtual' };\n              }\n              return undefined;\n            });\n\n            /* 2️⃣  Load the module from the map */\n            build.onLoad({ filter: /.*/, namespace: 'virtual' }, args => {\n              const contents = sourceFilesMap.get(args.path);\n              if (contents == null) throw new StackAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);\n\n              const ext = args.path.split('.').pop() ?? '';\n              const loader = extToLoader.get(ext) ?? throwErr(`esbuild requested file ${args.path} with unknown extension ${ext}`);\n\n              return { contents, loader };\n            });\n          },\n        },\n      ],\n    }));\n  } catch (e) {\n    if (e instanceof Error && e.message.startsWith(\"Build failed with \")) {\n      return Result.error(e.message);\n    }\n    throw e;\n  }\n\n  if (result.errors.length > 0) {\n    return Result.error(result.errors.map(e => e.text).join('\\n'));\n  }\n\n  if (result.outputFiles.length > 0) {\n    return Result.ok(result.outputFiles[0].text);\n  }\n  return throwErr(\"No output generated??\");\n}\n"],"mappings":"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","names":["build","result"]}

package/dist/esm/utils/globals.js

@@ -11,6 +11,17 @@ function createGlobal(key, init) {
   }
   return globalVar[stackGlobalsSymbol][key];
 }
+function createGlobalAsync(key, init) {
+  let promise = null;
+  if (!globalVar[stackGlobalsSymbol][key]) {
+    promise = init().catch((e) => {
+      delete globalVar[stackGlobalsSymbol][key];
+      throw e;
+    });
+    globalVar[stackGlobalsSymbol][key] = promise;
+  }
+  return promise ?? globalVar[stackGlobalsSymbol][key];
+}
 function getGlobal(key) {
   return globalVar[stackGlobalsSymbol][key];
 }
@@ -19,6 +30,7 @@ function setGlobal(key, value) {
 }
 export {
   createGlobal,
+  createGlobalAsync,
   getGlobal,
   globalVar,
   setGlobal

package/dist/esm/utils/globals.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/utils/globals.tsx"],"sourcesContent":["const globalVar: any =\n  typeof globalThis !== 'undefined' ? globalThis :\n    typeof global !== 'undefined' ? global :\n      typeof window !== 'undefined' ? window :\n        typeof self !== 'undefined' ? self :\n          {};\nexport {\n  globalVar\n};\n\nif (typeof globalThis === 'undefined') {\n  (globalVar as any).globalThis = globalVar;\n}\n\nconst stackGlobalsSymbol = Symbol.for('__stack-globals');\nglobalVar[stackGlobalsSymbol] ??= {};\n\nexport function createGlobal<T>(key: string, init: () => T) {\n  if (!globalVar[stackGlobalsSymbol][key]) {\n    globalVar[stackGlobalsSymbol][key] = init();\n  }\n  return globalVar[stackGlobalsSymbol][key] as T;\n}\n\nexport function getGlobal(key: string): any {\n  return globalVar[stackGlobalsSymbol][key];\n}\n\nexport function setGlobal(key: string, value: any) {\n  globalVar[stackGlobalsSymbol][key] = value;\n}\n"],"mappings":";AAAA,IAAM,YACJ,OAAO,eAAe,cAAc,aAClC,OAAO,WAAW,cAAc,SAC9B,OAAO,WAAW,cAAc,SAC9B,OAAO,SAAS,cAAc,OAC5B,CAAC;AAKX,IAAI,OAAO,eAAe,aAAa;AACrC,EAAC,UAAkB,aAAa;AAClC;AAEA,IAAM,qBAAqB,OAAO,IAAI,iBAAiB;AACvD,UAAU,kBAAkB,MAAM,CAAC;AAE5B,SAAS,aAAgB,KAAa,MAAe;AAC1D,MAAI,CAAC,UAAU,kBAAkB,EAAE,GAAG,GAAG;AACvC,cAAU,kBAAkB,EAAE,GAAG,IAAI,KAAK;AAAA,EAC5C;AACA,SAAO,UAAU,kBAAkB,EAAE,GAAG;AAC1C;AAEO,SAAS,UAAU,KAAkB;AAC1C,SAAO,UAAU,kBAAkB,EAAE,GAAG;AAC1C;AAEO,SAAS,UAAU,KAAa,OAAY;AACjD,YAAU,kBAAkB,EAAE,GAAG,IAAI;AACvC;","names":[]}
+{"version":3,"sources":["../../../src/utils/globals.tsx"],"sourcesContent":["const globalVar: any =\n  typeof globalThis !== 'undefined' ? globalThis :\n    typeof global !== 'undefined' ? global :\n      typeof window !== 'undefined' ? window :\n        typeof self !== 'undefined' ? self :\n          {};\nexport {\n  globalVar\n};\n\nif (typeof globalThis === 'undefined') {\n  (globalVar as any).globalThis = globalVar;\n}\n\nconst stackGlobalsSymbol = Symbol.for('__stack-globals');\nglobalVar[stackGlobalsSymbol] ??= {};\n\nexport function createGlobal<T>(key: string, init: () => T) {\n  if (!globalVar[stackGlobalsSymbol][key]) {\n    globalVar[stackGlobalsSymbol][key] = init();\n  }\n  return globalVar[stackGlobalsSymbol][key] as T;\n}\n\n/**\n * Like createGlobal, but if the asynchronous initialization fails, the global will be reset and recomputed on the next\n * invocation.\n */\nexport function createGlobalAsync<T>(key: string, init: () => Promise<T>): Promise<T> {\n  let promise: Promise<T> | null = null;\n  if (!globalVar[stackGlobalsSymbol][key]) {\n    promise = init().catch((e) => {\n      delete globalVar[stackGlobalsSymbol][key];\n      throw e;\n    });\n    globalVar[stackGlobalsSymbol][key] = promise;\n  }\n  return promise ?? globalVar[stackGlobalsSymbol][key] as Promise<T>;\n}\n\nexport function getGlobal(key: string): any {\n  return globalVar[stackGlobalsSymbol][key];\n}\n\nexport function setGlobal(key: string, value: any) {\n  globalVar[stackGlobalsSymbol][key] = value;\n}\n"],"mappings":";AAAA,IAAM,YACJ,OAAO,eAAe,cAAc,aAClC,OAAO,WAAW,cAAc,SAC9B,OAAO,WAAW,cAAc,SAC9B,OAAO,SAAS,cAAc,OAC5B,CAAC;AAKX,IAAI,OAAO,eAAe,aAAa;AACrC,EAAC,UAAkB,aAAa;AAClC;AAEA,IAAM,qBAAqB,OAAO,IAAI,iBAAiB;AACvD,UAAU,kBAAkB,MAAM,CAAC;AAE5B,SAAS,aAAgB,KAAa,MAAe;AAC1D,MAAI,CAAC,UAAU,kBAAkB,EAAE,GAAG,GAAG;AACvC,cAAU,kBAAkB,EAAE,GAAG,IAAI,KAAK;AAAA,EAC5C;AACA,SAAO,UAAU,kBAAkB,EAAE,GAAG;AAC1C;AAMO,SAAS,kBAAqB,KAAa,MAAoC;AACpF,MAAI,UAA6B;AACjC,MAAI,CAAC,UAAU,kBAAkB,EAAE,GAAG,GAAG;AACvC,cAAU,KAAK,EAAE,MAAM,CAAC,MAAM;AAC5B,aAAO,UAAU,kBAAkB,EAAE,GAAG;AACxC,YAAM;AAAA,IACR,CAAC;AACD,cAAU,kBAAkB,EAAE,GAAG,IAAI;AAAA,EACvC;AACA,SAAO,WAAW,UAAU,kBAAkB,EAAE,GAAG;AACrD;AAEO,SAAS,UAAU,KAAkB;AAC1C,SAAO,UAAU,kBAAkB,EAAE,GAAG;AAC1C;AAEO,SAAS,UAAU,KAAa,OAAY;AACjD,YAAU,kBAAkB,EAAE,GAAG,IAAI;AACvC;","names":[]}

package/dist/esm/utils/paginated-lists.js

@@ -1,24 +1,44 @@
 // src/utils/paginated-lists.tsx
-import { range } from "./arrays.js";
 import { StackAssertionError } from "./errors.js";
 var PaginatedList = class _PaginatedList {
   // Implementations
+  /** Returns the cursor pointing to the start of the list (before any items). */
   getFirstCursor() {
     return this._getFirstCursor();
   }
+  /** Returns the cursor pointing to the end of the list (after all items). */
   getLastCursor() {
     return this._getLastCursor();
   }
+  /** Compares two items according to the given orderBy. Returns negative if a < b, 0 if equal, positive if a > b. */
   compare(orderBy, a, b) {
     return this._compare(orderBy, a, b);
   }
+  /**
+   * Fetches items moving forward ('next') or backward ('prev') from the given cursor.
+   *
+   * Respects `limitPrecision`: 'exact' guarantees the exact limit, 'at-least'/'at-most'/'approximate'
+   * allow flexibility for performance. Returns items, boundary flags, and a new cursor.
+   *
+   * @example
+   * ```ts
+   * // Get 5 items after the start
+   * const result = await list.nextOrPrev('next', { cursor: list.getFirstCursor(), limit: 5, filter: {}, orderBy: 'asc', limitPrecision: 'exact' });
+   * // result.items.length === 5 (or less if list has fewer items)
+   * // result.isFirst === true (started at first cursor)
+   * // result.isLast === true if we got all remaining items
+   *
+   * // Continue from where we left off
+   * const more = await list.nextOrPrev('next', { cursor: result.cursor, limit: 5, ... });
+   * ```
+   */
   async nextOrPrev(type, options) {
     let result = [];
     let includesFirst = false;
     let includesLast = false;
     let cursor = options.cursor;
     let limitRemaining = options.limit;
-    while (limitRemaining > 0 || type === "next" && includesLast || type === "prev" && includesFirst) {
+    while (limitRemaining > 0 && (type !== "next" || !includesLast) && (type !== "prev" || !includesFirst)) {
       const iterationRes = await this._nextOrPrev(type, {
         cursor,
         limit: options.limit,
@@ -46,21 +66,23 @@ var PaginatedList = class _PaginatedList {
       if (type === "next") {
         result = result.slice(0, options.limit);
         includesLast = false;
-        if (options.limit > 0) cursor = result[result.length - 1].itemCursor;
+        if (options.limit > 0) cursor = result[result.length - 1].nextCursor;
       } else {
         result = result.slice(result.length - options.limit);
         includesFirst = false;
-        if (options.limit > 0) cursor = result[0].itemCursor;
+        if (options.limit > 0) cursor = result[0].prevCursor;
       }
     }
     return { items: result, isFirst: includesFirst, isLast: includesLast, cursor };
   }
+  /** Fetches items after the given cursor (forward pagination). */
   async next({ after, ...rest }) {
     return await this.nextOrPrev("next", {
       ...rest,
       cursor: after
     });
   }
+  /** Fetches items before the given cursor (backward pagination). */
   async prev({ before, ...rest }) {
     return await this.nextOrPrev("prev", {
       ...rest,
@@ -68,6 +90,27 @@ var PaginatedList = class _PaginatedList {
     });
   }
   // Utility methods below
+  /**
+   * Transforms this list by mapping each item to zero or more new items.
+   *
+   * Note that the sort order must be preserved after the operation; the flat-mapped list will not be sorted automatically.
+   *
+   * @param itemMapper - Maps each item (with its cursor) to an array of new items
+   * @param compare - Comparison function for the new item type
+   * @param newCursorFromOldCursor/oldCursorFromNewCursor - Cursor conversion functions
+   * @param estimateItemsToFetch - Estimates how many source items to fetch for a given limit
+   *
+   * @example
+   * ```ts
+   * // Expand orders into line items (1 order -> N line items)
+   * const lineItems = ordersList.flatMap({
+   *   itemMapper: ({ item: order }) => order.lineItems.map((li, i) => ({ item: li, prevCursor: `${order.id}-${i}`, nextCursor: `${order.id}-${i + 1}` })),
+   *   compare: (_, a, b) => a.createdAt - b.createdAt,
+   *   estimateItemsToFetch: ({ limit }) => Math.ceil(limit / 3), // avg 3 items per order
+   *   // ... cursor converters
+   * });
+   * ```
+   */
   flatMap(options) {
     const that = this;
     class FlatMapPaginatedList extends _PaginatedList {
@@ -104,10 +147,27 @@ var PaginatedList = class _PaginatedList {
     }
     return new FlatMapPaginatedList();
   }
+  /**
+   * Transforms each item in the list. Requires a reverse mapper for comparison delegation.
+   *
+   * @param itemMapper - Transforms each item
+   * @param oldItemFromNewItem - Reverse-maps new items back to old items (for comparison)
+   *
+   * @example
+   * ```ts
+   * // Convert User objects to UserDTO
+   * const userDtos = usersList.map({
+   *   itemMapper: (user) => ({ id: user.id, displayName: user.name }),
+   *   oldItemFromNewItem: (dto) => fullUsers.get(dto.id)!, // for comparison
+   *   oldFilterFromNewFilter: (f) => f,
+   *   oldOrderByFromNewOrderBy: (o) => o,
+   * });
+   * ```
+   */
   map(options) {
     return this.flatMap({
       itemMapper: (itemEntry, filter, orderBy) => {
-        return [{ item: options.itemMapper(itemEntry.item), itemCursor: itemEntry.itemCursor }];
+        return [{ item: options.itemMapper(itemEntry.item), prevCursor: itemEntry.prevCursor, nextCursor: itemEntry.nextCursor }];
       },
       compare: (orderBy, a, b) => this.compare(options.oldOrderByFromNewOrderBy(orderBy), options.oldItemFromNewItem(a), options.oldItemFromNewItem(b)),
       newCursorFromOldCursor: (cursor) => cursor,
@@ -117,6 +177,22 @@ var PaginatedList = class _PaginatedList {
       estimateItemsToFetch: (options2) => options2.limit
     });
   }
+  /**
+   * Filters items in the list. Requires an estimate function since filtering may reduce output.
+   *
+   * @param filter - Predicate to include/exclude items
+   * @param estimateItemsToFetch - Estimates how many source items to fetch (accounts for filter selectivity)
+   *
+   * @example
+   * ```ts
+   * // Filter to only active users
+   * const activeUsers = usersList.filter({
+   *   filter: (user, filterOpts) => user.isActive && user.role === filterOpts.role,
+   *   oldFilterFromNewFilter: (f) => ({}), // original list has no filter
+   *   estimateItemsToFetch: ({ limit }) => limit * 2, // expect ~50% active
+   * });
+   * ```
+   */
   filter(options) {
     return this.flatMap({
       itemMapper: (itemEntry, filter, orderBy) => options.filter(itemEntry.item, filter) ? [itemEntry] : [],
@@ -128,6 +204,20 @@ var PaginatedList = class _PaginatedList {
       estimateItemsToFetch: (o) => options.estimateItemsToFetch(o)
     });
   }
+  /**
+   * Adds an additional filter constraint while preserving the original filter type.
+   * Shorthand for `filter()` that intersects Filter with AddedFilter.
+   *
+   * @example
+   * ```ts
+   * // Add a "verified" filter on top of existing filters
+   * const verifiedUsers = usersList.addFilter({
+   *   filter: (user, f) => user.emailVerified,
+   *   estimateItemsToFetch: ({ limit }) => limit * 2, // ~50% are verified
+   * });
+   * // verifiedUsers filter type is Filter
+   * ```
+   */
   addFilter(options) {
     return this.filter({
       filter: (item, filter) => options.filter(item, filter),
@@ -135,6 +225,20 @@ var PaginatedList = class _PaginatedList {
       estimateItemsToFetch: (o) => options.estimateItemsToFetch(o)
     });
   }
+  /**
+   * Merges multiple paginated lists into one, interleaving items by sort order.
+   * All lists must use the same compare function.
+   *
+   * The merged cursor is a JSON-encoded array of individual list cursors.
+   *
+   * @example
+   * ```ts
+   * // Merge users from multiple sources into a unified feed
+   * const allUsers = PaginatedList.merge(internalUsers, externalUsers, partnerUsers);
+   * const page = await allUsers.next({ after: allUsers.getFirstCursor(), limit: 20, ... });
+   * // page.items contains interleaved items from all sources, sorted by orderBy
+   * ```
+   */
   static merge(...lists) {
     class MergePaginatedList extends _PaginatedList {
       _getFirstCursor() {
@@ -146,7 +250,7 @@ var PaginatedList = class _PaginatedList {
       _compare(orderBy, a, b) {
         const listsResults = lists.map((list) => list.compare(orderBy, a, b));
         if (!listsResults.every((result) => result === listsResults[0])) {
-          throw new StackAssertionError("Lists have different compare results; make sure that they use the same compare function", { lists, listsResults });
+          throw new StackAssertionError("Lists have different compare results; make sure that they use the same compare function", { lists, listsResults, orderBy, a, b });
         }
         return listsResults[0];
       }
@@ -163,20 +267,40 @@ var PaginatedList = class _PaginatedList {
         }));
         const combinedItems = fetchedLists.flatMap((list, i) => list.items.map((itemEntry) => ({ itemEntry, listIndex: i })));
         const sortedItems = [...combinedItems].sort((a, b) => this._compare(orderBy, a.itemEntry.item, b.itemEntry.item));
-        const lastCursorForEachList = sortedItems.reduce((acc, item) => {
-          acc[item.listIndex] = item.itemEntry.itemCursor;
-          return acc;
-        }, range(lists.length).map((i) => cursors[i]));
+        const sortedItemsWithMergedCursors = [];
+        const curCursors = [...cursors];
+        for (const item of type === "next" ? sortedItems : sortedItems.reverse()) {
+          const lastCursors = [...curCursors];
+          curCursors[item.listIndex] = type === "next" ? item.itemEntry.nextCursor : item.itemEntry.prevCursor;
+          sortedItemsWithMergedCursors.push({
+            item: item.itemEntry.item,
+            prevCursor: type === "next" ? JSON.stringify(lastCursors) : JSON.stringify(curCursors),
+            nextCursor: type === "next" ? JSON.stringify(curCursors) : JSON.stringify(lastCursors)
+          });
+        }
+        if (type === "prev") {
+          sortedItemsWithMergedCursors.reverse();
+        }
         return {
-          items: sortedItems.map((item) => item.itemEntry),
-          isFirst: sortedItems.every((item) => item.listIndex === 0),
-          isLast: sortedItems.every((item) => item.listIndex === lists.length - 1),
-          cursor: JSON.stringify(lastCursorForEachList)
+          items: sortedItemsWithMergedCursors,
+          isFirst: fetchedLists.every((list) => list.isFirst),
+          isLast: fetchedLists.every((list) => list.isLast),
+          cursor: JSON.stringify(curCursors)
         };
       }
     }
     return new MergePaginatedList();
   }
+  /**
+   * Returns an empty paginated list that always returns no items.
+   *
+   * @example
+   * ```ts
+   * const empty = PaginatedList.empty();
+   * const result = await empty.next({ after: empty.getFirstCursor(), limit: 10, ... });
+   * // result = { items: [], isFirst: true, isLast: true, cursor: "first" }
+   * ```
+   */
   static empty() {
     class EmptyPaginatedList extends _PaginatedList {
       _getFirstCursor() {
@@ -201,10 +325,10 @@ var ArrayPaginatedList = class extends PaginatedList {
     this.array = array;
   }
   _getFirstCursor() {
-    return "0";
+    return "before-0";
   }
   _getLastCursor() {
-    return `${this.array.length - 1}`;
+    return `before-${this.array.length}`;
   }
   _compare(orderBy, a, b) {
     return orderBy(a, b);
@@ -212,14 +336,20 @@ var ArrayPaginatedList = class extends PaginatedList {
   async _nextOrPrev(type, options) {
     const filteredArray = this.array.filter(options.filter);
     const sortedArray = [...filteredArray].sort((a, b) => this._compare(options.orderBy, a, b));
-    const itemEntriesArray = sortedArray.map((item, index) => ({ item, itemCursor: `${index}` }));
-    const oldCursor = Number(options.cursor);
-    const newCursor = Math.max(0, Math.min(this.array.length - 1, oldCursor + (type === "next" ? 1 : -1) * options.limit));
+    const itemEntriesArray = sortedArray.map((item, index) => ({
+      item,
+      prevCursor: `before-${index}`,
+      nextCursor: `before-${index + 1}`
+    }));
+    const oldCursor = Number(options.cursor.replace("before-", ""));
+    const clampedOldCursor = Math.max(0, Math.min(sortedArray.length, oldCursor));
+    const newCursor = Math.max(0, Math.min(sortedArray.length, clampedOldCursor + (type === "next" ? 1 : -1) * options.limit));
+    const slicedItemEntriesArray = itemEntriesArray.slice(Math.min(clampedOldCursor, newCursor), Math.max(clampedOldCursor, newCursor));
     return {
-      items: itemEntriesArray.slice(Math.min(oldCursor, newCursor), Math.max(oldCursor, newCursor)),
-      isFirst: oldCursor === 0 || newCursor === 0,
-      isLast: oldCursor === this.array.length - 1 || newCursor === this.array.length - 1,
-      cursor: `${newCursor}`
+      items: slicedItemEntriesArray,
+      isFirst: clampedOldCursor === 0 || newCursor === 0,
+      isLast: clampedOldCursor === sortedArray.length || newCursor === sortedArray.length,
+      cursor: `before-${newCursor}`
     };
   }
 };