@stackframe/stack-shared 2.8.39 → 2.8.40

package/dist/sessions.d.ts

@@ -1,9 +1,27 @@
-import * as jose from 'jose';
+import { InferType } from 'yup';
+import { accessTokenPayloadSchema } from './schema-fields.js';
+import './utils/currency-constants.js';
+import './utils/dates.js';
 
+type AccessTokenPayload = InferType<typeof accessTokenPayloadSchema>;
 declare class AccessToken {
     readonly token: string;
     constructor(token: string);
-    get decoded(): jose.JWTPayload;
+    get payload(): {
+        exp?: number | undefined;
+        sub: string;
+        name: string | null;
+        iss: string;
+        aud: string;
+        project_id: string;
+        branch_id: string;
+        refresh_token_id: string;
+        role: "authenticated";
+        email: string | null;
+        email_verified: boolean;
+        selected_team_id: string | null;
+        is_anonymous: boolean;
+    };
     get expiresAt(): Date;
     /**
      * @returns The number of milliseconds until the access token expires, or 0 if it has already expired.
@@ -62,12 +80,16 @@ declare class InternalSession {
     onInvalidate(callback: () => void): {
         unsubscribe: () => void;
     };
+    /**
+     * Returns the access token if it is found in the cache and not expired yet, or null otherwise. Never fetches new tokens.
+     */
+    getAccessTokenIfNotExpiredYet(minMillisUntilExpiration: number): AccessToken | null;
     /**
      * Returns the access token if it is found in the cache, fetching it otherwise.
      *
      * 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).
      *
-     * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
+     * @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.
      */
     getOrFetchLikelyValidTokens(minMillisUntilExpiration: number): Promise<{
         accessToken: AccessToken;
@@ -106,4 +128,4 @@ declare class InternalSession {
     private _refreshAndSetRefreshPromise;
 }
 
-export { AccessToken, InternalSession, RefreshToken };
+export { AccessToken, type AccessTokenPayload, InternalSession, RefreshToken };

package/dist/sessions.js

@@ -36,6 +36,7 @@ __export(sessions_exports, {
 });
 module.exports = __toCommonJS(sessions_exports);
 var jose = __toESM(require("jose"));
+var import_schema_fields = require("./schema-fields.js");
 var import_errors = require("./utils/errors.js");
 var import_stores = require("./utils/stores.js");
 var AccessToken = class {
@@ -45,11 +46,12 @@ var AccessToken = class {
       throw new import_errors.StackAssertionError("Access token is the string 'undefined'; it's unlikely this is the correct value. They're supposed to be unguessable!");
     }
   }
-  get decoded() {
-    return jose.decodeJwt(this.token);
+  get payload() {
+    const payload = jose.decodeJwt(this.token);
+    return import_schema_fields.accessTokenPayloadSchema.validateSync(payload);
   }
   get expiresAt() {
-    const { exp } = this.decoded;
+    const { exp } = this.payload;
     if (exp === void 0) return /* @__PURE__ */ new Date(864e13);
     return new Date(exp * 1e3);
   }
@@ -113,19 +115,27 @@ var InternalSession = class _InternalSession {
   onInvalidate(callback) {
     return this._knownToBeInvalid.onChange(() => callback());
   }
+  /**
+   * Returns the access token if it is found in the cache and not expired yet, or null otherwise. Never fetches new tokens.
+   */
+  getAccessTokenIfNotExpiredYet(minMillisUntilExpiration) {
+    if (minMillisUntilExpiration > 6e4) {
+      throw new Error(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short to be used for more than 60s`);
+    }
+    const accessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();
+    if (!accessToken || accessToken.expiresInMillis < minMillisUntilExpiration) return null;
+    return accessToken;
+  }
   /**
    * Returns the access token if it is found in the cache, fetching it otherwise.
    *
    * 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).
    *
-   * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
+   * @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.
    */
   async getOrFetchLikelyValidTokens(minMillisUntilExpiration) {
-    if (minMillisUntilExpiration >= 6e4) {
-      throw new Error(`Required access token expiry ${minMillisUntilExpiration}ms is too long; access tokens are too short to be used for more than 60s`);
-    }
-    const accessToken = this._getPotentiallyInvalidAccessTokenIfAvailable();
-    if (!accessToken || accessToken.expiresInMillis < minMillisUntilExpiration) {
+    const accessToken = this.getAccessTokenIfNotExpiredYet(minMillisUntilExpiration);
+    if (!accessToken) {
       const newTokens = await this.fetchNewTokens();
       const expiresInMillis = newTokens?.accessToken.expiresInMillis;
       if (expiresInMillis && expiresInMillis < minMillisUntilExpiration) {

package/dist/sessions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sessions.ts"],"sourcesContent":["import * as jose from 'jose';\nimport { StackAssertionError } from \"./utils/errors\";\nimport { Store } from \"./utils/stores\";\n\nexport class AccessToken {\n  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 decoded() {\n    return jose.decodeJwt(this.token);\n  }\n\n  get expiresAt(): Date {\n    const { exp } = this.decoded;\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 ? new AccessToken(_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, 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 (which may or may not be valid still), or new tokens otherwise.\n   */\n  async getOrFetchLikelyValidTokens(minMillisUntilExpiration: number): Promise<{ accessToken: AccessToken, refreshToken: RefreshToken | null } | 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) {\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 } from \"./utils/errors\";\nimport { Store } from \"./utils/stores\";\n\n\nexport type AccessTokenPayload = InferType<typeof accessTokenPayloadSchema>;\n\nexport class AccessToken {\n  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    const payload = jose.decodeJwt(this.token);\n    return accessTokenPayloadSchema.validateSync(payload);\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 ? new AccessToken(_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":[]}

package/dist/utils/paginated-lists.d.mts

@@ -0,0 +1,176 @@
+type QueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = {
+    filter: Filter;
+    orderBy: OrderBy;
+    limit: number;
+    /**
+     * Whether the limit should be treated as an exact value, or an approximate value.
+     *
+     * If set to 'exact', less items will only be returned if the list item is the first or last item.
+     *
+     * If set to 'at-least' or 'approximate', the implementation may decide to return more items than the limit requested if doing so comes at no (or negligible) extra cost.
+     *
+     * If set to 'at-most' or 'approximate', the implementation may decide to return less items than the limit requested if requesting more items would come at a non-negligible extra cost. In this case, if limit > 0, the implementation must still make progress towards the end of the list and the returned cursor must be different from the one passed in.
+     *
+     * Defaults to 'exact'.
+     */
+    limitPrecision: 'exact' | 'at-least' | 'at-most' | 'approximate';
+} & ([Type] extends [never] ? unknown : [Type] extends ['next'] ? {
+    after: Cursor;
+} : [Type] extends ['prev'] ? {
+    before: Cursor;
+} : {
+    cursor: Cursor;
+});
+type ImplQueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = QueryOptions<Type, Cursor, Filter, OrderBy> & {
+    limitPrecision: 'approximate';
+};
+type QueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+type ImplQueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+declare abstract class PaginatedList<Item, Cursor extends string, Filter extends unknown, OrderBy extends unknown> {
+    protected abstract _getFirstCursor(): Cursor;
+    protected abstract _getLastCursor(): Cursor;
+    protected abstract _compare(orderBy: OrderBy, a: Item, b: Item): number;
+    protected abstract _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<ImplQueryResult<Item, Cursor>>;
+    getFirstCursor(): Cursor;
+    getLastCursor(): Cursor;
+    compare(orderBy: OrderBy, a: Item, b: Item): number;
+    nextOrPrev(type: 'next' | 'prev', options: QueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    next({ after, ...rest }: QueryOptions<'next', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    prev({ before, ...rest }: QueryOptions<'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (itemEntry: {
+            item: Item;
+            itemCursor: Cursor;
+        }, filter: Filter2, orderBy: OrderBy2) => {
+            item: Item2;
+            itemCursor: Cursor2;
+        }[];
+        compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+        newCursorFromOldCursor: (cursor: Cursor) => Cursor2;
+        oldCursorFromNewCursor: (cursor: Cursor2) => Cursor;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy2;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+    map<Item2, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (item: Item) => Item2;
+        oldItemFromNewItem: (item: Item2) => Item;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+    }): PaginatedList<Item2, Cursor, Filter2, OrderBy2>;
+    filter<Filter2 extends unknown>(options: {
+        filter: (item: Item, filter: Filter2) => boolean;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter2, OrderBy>;
+    addFilter<AddedFilter extends unknown>(options: {
+        filter: (item: Item, filter: Filter & AddedFilter) => boolean;
+        estimateItemsToFetch: (options: {
+            filter: Filter & AddedFilter;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter & AddedFilter, OrderBy>;
+    static merge<Item, Filter extends unknown, OrderBy extends unknown>(...lists: PaginatedList<Item, any, Filter, OrderBy>[]): PaginatedList<Item, string, Filter, OrderBy>;
+    static empty(): {
+        _getFirstCursor(): "first";
+        _getLastCursor(): "last";
+        _compare(orderBy: any, a: any, b: any): number;
+        _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', string, any, any>): Promise<{
+            items: never[];
+            isFirst: boolean;
+            isLast: boolean;
+            cursor: "first";
+        }>;
+        getFirstCursor(): "first" | "last";
+        getLastCursor(): "first" | "last";
+        compare(orderBy: any, a: never, b: never): number;
+        nextOrPrev(type: "next" | "prev", options: QueryOptions<"next" | "prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        next({ after, ...rest }: QueryOptions<"next", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        prev({ before, ...rest }: QueryOptions<"prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+            itemMapper: (itemEntry: {
+                item: never;
+                itemCursor: "first" | "last";
+            }, filter: Filter2, orderBy: OrderBy2) => {
+                item: Item2;
+                itemCursor: Cursor2;
+            }[];
+            compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+            newCursorFromOldCursor: (cursor: "first" | "last") => Cursor2;
+            oldCursorFromNewCursor: (cursor: Cursor2) => "first" | "last";
+            oldFilterFromNewFilter: (filter: Filter2) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2;
+                orderBy: OrderBy2;
+                limit: number;
+            }) => number;
+        }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+        map<Item2_1, Filter2_1 extends unknown, OrderBy2_1 extends unknown>(options: {
+            itemMapper: (item: never) => Item2_1;
+            oldItemFromNewItem: (item: Item2_1) => never;
+            oldFilterFromNewFilter: (filter: Filter2_1) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2_1) => any;
+        }): PaginatedList<Item2_1, "first" | "last", Filter2_1, OrderBy2_1>;
+        filter<Filter2_2 extends unknown>(options: {
+            filter: (item: never, filter: Filter2_2) => boolean;
+            oldFilterFromNewFilter: (filter: Filter2_2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2_2;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", Filter2_2, any>;
+        addFilter<AddedFilter extends unknown>(options: {
+            filter: (item: never, filter: any) => boolean;
+            estimateItemsToFetch: (options: {
+                filter: any;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", any, any>;
+    };
+}
+declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
+    private readonly array;
+    constructor(array: Item[]);
+    _getFirstCursor(): "0";
+    _getLastCursor(): `${number}`;
+    _compare(orderBy: (a: Item, b: Item) => number, a: Item, b: Item): number;
+    _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number>): Promise<{
+        items: {
+            item: Item;
+            itemCursor: `${number}`;
+        }[];
+        isFirst: boolean;
+        isLast: boolean;
+        cursor: `${number}`;
+    }>;
+}
+
+export { ArrayPaginatedList, PaginatedList };

package/dist/utils/paginated-lists.d.ts

@@ -0,0 +1,176 @@
+type QueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = {
+    filter: Filter;
+    orderBy: OrderBy;
+    limit: number;
+    /**
+     * Whether the limit should be treated as an exact value, or an approximate value.
+     *
+     * If set to 'exact', less items will only be returned if the list item is the first or last item.
+     *
+     * If set to 'at-least' or 'approximate', the implementation may decide to return more items than the limit requested if doing so comes at no (or negligible) extra cost.
+     *
+     * If set to 'at-most' or 'approximate', the implementation may decide to return less items than the limit requested if requesting more items would come at a non-negligible extra cost. In this case, if limit > 0, the implementation must still make progress towards the end of the list and the returned cursor must be different from the one passed in.
+     *
+     * Defaults to 'exact'.
+     */
+    limitPrecision: 'exact' | 'at-least' | 'at-most' | 'approximate';
+} & ([Type] extends [never] ? unknown : [Type] extends ['next'] ? {
+    after: Cursor;
+} : [Type] extends ['prev'] ? {
+    before: Cursor;
+} : {
+    cursor: Cursor;
+});
+type ImplQueryOptions<Type extends 'next' | 'prev', Cursor, Filter, OrderBy> = QueryOptions<Type, Cursor, Filter, OrderBy> & {
+    limitPrecision: 'approximate';
+};
+type QueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+type ImplQueryResult<Item, Cursor> = {
+    items: {
+        item: Item;
+        itemCursor: Cursor;
+    }[];
+    isFirst: boolean;
+    isLast: boolean;
+    cursor: Cursor;
+};
+declare abstract class PaginatedList<Item, Cursor extends string, Filter extends unknown, OrderBy extends unknown> {
+    protected abstract _getFirstCursor(): Cursor;
+    protected abstract _getLastCursor(): Cursor;
+    protected abstract _compare(orderBy: OrderBy, a: Item, b: Item): number;
+    protected abstract _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<ImplQueryResult<Item, Cursor>>;
+    getFirstCursor(): Cursor;
+    getLastCursor(): Cursor;
+    compare(orderBy: OrderBy, a: Item, b: Item): number;
+    nextOrPrev(type: 'next' | 'prev', options: QueryOptions<'next' | 'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    next({ after, ...rest }: QueryOptions<'next', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    prev({ before, ...rest }: QueryOptions<'prev', Cursor, Filter, OrderBy>): Promise<QueryResult<Item, Cursor>>;
+    flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (itemEntry: {
+            item: Item;
+            itemCursor: Cursor;
+        }, filter: Filter2, orderBy: OrderBy2) => {
+            item: Item2;
+            itemCursor: Cursor2;
+        }[];
+        compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+        newCursorFromOldCursor: (cursor: Cursor) => Cursor2;
+        oldCursorFromNewCursor: (cursor: Cursor2) => Cursor;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy2;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+    map<Item2, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+        itemMapper: (item: Item) => Item2;
+        oldItemFromNewItem: (item: Item2) => Item;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => OrderBy;
+    }): PaginatedList<Item2, Cursor, Filter2, OrderBy2>;
+    filter<Filter2 extends unknown>(options: {
+        filter: (item: Item, filter: Filter2) => boolean;
+        oldFilterFromNewFilter: (filter: Filter2) => Filter;
+        estimateItemsToFetch: (options: {
+            filter: Filter2;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter2, OrderBy>;
+    addFilter<AddedFilter extends unknown>(options: {
+        filter: (item: Item, filter: Filter & AddedFilter) => boolean;
+        estimateItemsToFetch: (options: {
+            filter: Filter & AddedFilter;
+            orderBy: OrderBy;
+            limit: number;
+        }) => number;
+    }): PaginatedList<Item, Cursor, Filter & AddedFilter, OrderBy>;
+    static merge<Item, Filter extends unknown, OrderBy extends unknown>(...lists: PaginatedList<Item, any, Filter, OrderBy>[]): PaginatedList<Item, string, Filter, OrderBy>;
+    static empty(): {
+        _getFirstCursor(): "first";
+        _getLastCursor(): "last";
+        _compare(orderBy: any, a: any, b: any): number;
+        _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', string, any, any>): Promise<{
+            items: never[];
+            isFirst: boolean;
+            isLast: boolean;
+            cursor: "first";
+        }>;
+        getFirstCursor(): "first" | "last";
+        getLastCursor(): "first" | "last";
+        compare(orderBy: any, a: never, b: never): number;
+        nextOrPrev(type: "next" | "prev", options: QueryOptions<"next" | "prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        next({ after, ...rest }: QueryOptions<"next", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        prev({ before, ...rest }: QueryOptions<"prev", "first" | "last", any, any>): Promise<QueryResult<never, "first" | "last">>;
+        flatMap<Item2, Cursor2 extends string, Filter2 extends unknown, OrderBy2 extends unknown>(options: {
+            itemMapper: (itemEntry: {
+                item: never;
+                itemCursor: "first" | "last";
+            }, filter: Filter2, orderBy: OrderBy2) => {
+                item: Item2;
+                itemCursor: Cursor2;
+            }[];
+            compare: (orderBy: OrderBy2, a: Item2, b: Item2) => number;
+            newCursorFromOldCursor: (cursor: "first" | "last") => Cursor2;
+            oldCursorFromNewCursor: (cursor: Cursor2) => "first" | "last";
+            oldFilterFromNewFilter: (filter: Filter2) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2;
+                orderBy: OrderBy2;
+                limit: number;
+            }) => number;
+        }): PaginatedList<Item2, Cursor2, Filter2, OrderBy2>;
+        map<Item2_1, Filter2_1 extends unknown, OrderBy2_1 extends unknown>(options: {
+            itemMapper: (item: never) => Item2_1;
+            oldItemFromNewItem: (item: Item2_1) => never;
+            oldFilterFromNewFilter: (filter: Filter2_1) => any;
+            oldOrderByFromNewOrderBy: (orderBy: OrderBy2_1) => any;
+        }): PaginatedList<Item2_1, "first" | "last", Filter2_1, OrderBy2_1>;
+        filter<Filter2_2 extends unknown>(options: {
+            filter: (item: never, filter: Filter2_2) => boolean;
+            oldFilterFromNewFilter: (filter: Filter2_2) => any;
+            estimateItemsToFetch: (options: {
+                filter: Filter2_2;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", Filter2_2, any>;
+        addFilter<AddedFilter extends unknown>(options: {
+            filter: (item: never, filter: any) => boolean;
+            estimateItemsToFetch: (options: {
+                filter: any;
+                orderBy: any;
+                limit: number;
+            }) => number;
+        }): PaginatedList<never, "first" | "last", any, any>;
+    };
+}
+declare class ArrayPaginatedList<Item> extends PaginatedList<Item, `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number> {
+    private readonly array;
+    constructor(array: Item[]);
+    _getFirstCursor(): "0";
+    _getLastCursor(): `${number}`;
+    _compare(orderBy: (a: Item, b: Item) => number, a: Item, b: Item): number;
+    _nextOrPrev(type: 'next' | 'prev', options: ImplQueryOptions<'next' | 'prev', `${number}`, (item: Item) => boolean, (a: Item, b: Item) => number>): Promise<{
+        items: {
+            item: Item;
+            itemCursor: `${number}`;
+        }[];
+        isFirst: boolean;
+        isLast: boolean;
+        cursor: `${number}`;
+    }>;
+}
+
+export { ArrayPaginatedList, PaginatedList };