@vandenberghinc/volt 1.2.5 → 1.2.6

package/backend/dist/cjs/backend/src/database/quota/quoata_v2.d.ts

@@ -1,533 +0,0 @@
-/**
- * @author Daan van den Bergh
- * @copyright © 2025 - 2025 Daan van den Bergh. All rights reserved.
- */
-import * as vlib from "@vandenberghinc/vlib";
-import { SystemError } from "../../errors/system_error.js";
-import { Collection, TransactionCollection } from "../collection.js";
-import type { Server } from "../../server.js";
-import { InvalidUsageError } from "../../errors/index.js";
-import { SafeInt } from "./safe_int.js";
-/**
- * The quota manager.
- * This manager can be used to manage and enforce usage quotas for different resources,
- * for instance limiting money spent on tokens, or for rate limiting purposes.
- *
- * For managing monetary quotas, it is advised to use a nano-scale amount system
- * (smallest unit integer accounting). See {@link Quota.to_nano} for converting to nano scale.
- *
- * The quota manager ties each operation to a specific user id. For creating system quota's you can
- * use a non numeric `uid` to simulate a `uid` if needed.
- *
- * @template Type The allowed type for {@link Query.type}, provided at class level.
- *
- * @nav Database
- * @docs
- */
-export declare class QuotaManager {
-    /** The collection for database operations. */
-    collection: Collection<QuotaManager.Document>;
-    /** The system error options. */
-    system_error: QuotaManager.Opts["system_error"];
-    /**
-     * Construct a new quota manager with a specific quota type.
-     *
-     * @throws {InvalidUsageError} If {@link QuotaManager.Opts.collection} is already initialized and does not have the correct index.
-     *                             If the passed collection has manually assigned fields for {@link Collection.record_version} or {@link Collection.on_transform_version}.
-     *                             If the passed collection is transaction based.
-     *
-     * @docs
-     */
-    constructor(opts: QuotaManager.Opts);
-    /**
-     * Helper to create consistent query objects for MongoDB.
-     */
-    private create_db_query;
-    /**
-     * Format a compact, human-readable quota identifier for logs and error messages.
-     *
-     * @param query An object carrying the `uid` and `id` fields.
-     * @returns A stable identifier of the form `<uid>:<id>`.
-     */
-    private format_quota_id;
-    /**
-     * Get current quota status without modifying it.
-     *
-     * @note The `opts.retry` field defaults to `25`.
-     * @note System load errors are not saved inside this function.
-     *
-     * @param query The quota identifier arguments.
-     * @param opts Additional load options.
-     *
-     * @returns A load result depending on `opts`, see {@link Collection.LoadResult}
-     *
-     * @throws {Collection.NotFoundError} When `opts.throw !== false` and the quota does not exist.
-     * @throws {Collection.LoadError} When `opts.throw !== false` and a database error was encountered during the load operation.
-     * @throws {Collection.InvalidUsageError} When `opts.throw !== false` and the query is invalid.
-     *
-     * @docs
-     */
-    get<Default extends Collection.LoadOpts.Default<QuotaManager.Document> = undefined, Projection extends Collection.LoadOpts.Projection = undefined, Throw extends Collection.LoadOpts.Throw = undefined>(query: QuotaManager.Query, opts?: Collection.LoadOpts<QuotaManager.Document, Default, Projection, Throw>): Promise<Collection.WithThrow<Throw, InvalidUsageError, Collection.LoadResult<QuotaManager.Document, Default, Projection, Throw>>>;
-    /**
-     * Get current quota status without modifying it.
-     *
-     * @param query The quota identifier arguments.
-     * @param opts Additional load options, see {@link Collection.LoadOpts}.
-     *
-     * @returns An object containing error or status information,
-     *          see {@link QuotaManager.GetStatusResult}
-     *
-     * @docs
-     */
-    get_status(query: QuotaManager.Query, opts?: Pick<Collection.LoadOpts, "timeout">): Promise<QuotaManager.GetStatusResult>;
-    /**
-     * List all quotas for a user, optionally filtered by type.
-     *
-     * @param uid The user identifier.
-     * @param type Optional quota type filter.
-     * @returns List of quotas with their current status.
-     *
-     * @docs
-     */
-    list({ uid, timeout, }: {
-        /** The user id of the quotas to list. */
-        uid: string;
-        /** Per-operation timeout in milliseconds, mapped to `maxTimeoutMS`. */
-        timeout?: number;
-    }): Promise<QuotaManager.ListedQuota[]>;
-    /**
-     * Update or save quota configuration (`max`, `interval`) for an existing quota document,
-     * automatically creating the document if it does not exist.
-     *
-     * This method never resets runtime fields on existing documents:
-     * - On update: only `max` and `interval` are changed.
-     * - On insert: `usage` is initialized to `0` and `start` to the current UNIX timestamp (seconds).
-     *
-     * @param quota The configuration document (identity + {@link Quota.Opts}). Fields `usage` and `start`
-     *              are forbidden at the type level and ignored defensively at runtime.
-     * @param opts  Additional save options; see {@link Collection.SaveOpts}.
-     *
-     * @note The `opts.throw` field defaults to `true`.
-     *
-     * @returns The updated (or newly created) quota document, or an error-like result depending on `opts.throw`.
-     *          See {@link Collection.SaveResult}.
-     *
-     * @throws {InvalidUsageError} When `opts.throw !== false` and validation fails.
-     * @throws {Collection.SaveError} When `opts.throw !== false` and a database error occurs during the save operation.
-     *
-     * @docs
-     */
-    set<Throw extends Collection.SaveOpts.Throw = true>(quota: QuotaManager.Document.Opts & {
-        usage?: never;
-        start?: never;
-    }, opts?: Pick<Collection.SaveOpts<undefined, true, Throw, true>, "throw" | "timeout">): Promise<Collection.WithThrow<Throw, InvalidUsageError, Collection.SaveResult<QuotaManager.Document, undefined, true, Throw>>>;
-    /**
-     * Reset quota usage to zero & timestamp to the current unix timestamp for the specified quota.
-     *
-     * @param query The quota identifier, see {@link QuotaManager.Query}.
-     * @param opts Additional save options, see {@link Collection.SaveOpts}
-     *
-     * @note The `opts.throw` field defaults to the default value of {@link Collection.SaveOpts.throw}.
-     *
-     * @returns The updated quota document after resetting quota or an error depending on `throw`.
-     *          See {@link Collection.SaveResult}.
-     *
-     * @throws {Collection.NotFoundError} When `opts.throw !== false` and the quota does not exist.
-     * @throws {Collection.SaveError} When `opts.throw !== false` and a database error was encountered during the save operation.
-     * @throws {Collection.InvalidUsageError} When `opts.throw !== false` and the query is invalid.
-     *
-     * @docs
-     */
-    reset_usage<Throw extends Collection.SaveOpts.Throw = undefined>(query: QuotaManager.Query, opts?: Pick<Collection.SaveOpts<undefined, true, Throw, false>, "throw" | "timeout">): Promise<Collection.WithThrow<Throw, InvalidUsageError, Collection.SaveResult<QuotaManager.Document, undefined, true, Throw>>>;
-    /**
-     * Delete all quotas for a user.
-     *
-     * @docs
-     */
-    delete_by_user({ uid }: {
-        uid: string;
-    }): Promise<void>;
-    /**
-     * Validate the required {@link limit_helper} parameters.
-     * @note Parameter `requested_usage` may be a negative number.
-     *
-     * @docs
-     */
-    private validate_limit_helper_params;
-    /**
-     * Validates quota limits and atomically increments usage if within bounds.
-     * Handles interval resets automatically in a single database operation.
-     *
-     * @warning Ensure the quota exists in the database, or define `upsert` to create it when needed.
-     *
-     * @note This automatically increments the quota usage with the requested usage when `perform_increment` is true.
-     *       When `perform_increment` is false, it only validates availability without modifying the database.
-     *
-     * @returns Success with updated quota info or validation/error details.
-     *
-     * @docs
-     *
-     */
-    limit_helper({ query, requested_usage, upsert, safety_ratio, check_limit, perform_increment, collection, }: QuotaManager.LimitOpts & {
-        /** Whether to enforce limit checks, defaults to `true`. */
-        check_limit?: boolean;
-        /** The database collection or transaction to use. */
-        collection: Collection<QuotaManager.Document> | TransactionCollection<QuotaManager.Document>;
-    }): Promise<QuotaManager.LimitFailure | QuotaManager.LimitSuccess>;
-    /**
-     * Validate quota limits and, optionally, atomically increment usage if within bounds.
-     * Handles interval resets automatically in a single database operation.
-     *
-     * @warning Ensure the quota exists in the database, or provide `upsert` to create it when needed.
-     *
-     * @param perform_increment When `true` (default), performs the atomic increment. When `false`,
-     *                          executes a dry-run validation without modifying the database.
-     *
-     * @note Negative `requested_usage` is not allowed. Use {@link increment} for decrements.
-     *
-     * @returns On success, returns the (possibly updated) quota and remaining capacity; on failure,
-     *          returns a diagnostic indicating why the request was rejected.
-     *
-     * @docs
-     */
-    limit({ query, requested_usage, upsert, safety_ratio, perform_increment }: QuotaManager.LimitOpts & {
-        /** Whether to perform the increment, defaults to `true`. */
-        perform_increment?: boolean;
-    }): Promise<QuotaManager.LimitFailure | QuotaManager.LimitSuccess>;
-    /**
-     * Increment the usage on a quota.
-     *
-     * @warning This does not check for quota limits.
-     * @warning Ensure the quota exists in the database, or define `upsert` to create it when needed.
-     *
-     * @note This function allows for negative `requested_usage` values.
-     *
-     * @returns The updated quota record or a diagnostic if the quota was not found in the database or if the max retries have been exceeded.
-     *
-     * @docs
-     */
-    increment({ query, requested_usage, upsert, }: Omit<QuotaManager.LimitOpts, "safety_ratio">): Promise<QuotaManager.LimitFailure | QuotaManager.LimitSuccess>;
-    /**
-     * Validates multiple quota limits and atomically increments usage if within bounds.
-     * Handles interval resets automatically in a single database operation.
-     *
-     * This transaction based operation only commits changes if all quotas pass validation.
-     *
-     * @warning Ensure the quota exists in the database.
-     *
-     * @note This function does not allow for negative usage values, use {@link increment} for decrements.
-     * @note This automatically increments the quota usage with the requested usage.
-     *
-     * @param limits The quota limits to validate and increment upon success, or roll back upon failure.
-     *
-     * @returns Success with updated quota info or validation/error details.
-     *
-     * @docs
-     */
-    batch_limit({ limits }: {
-        limits: QuotaManager.BatchLimit[];
-    }): Promise<QuotaManager.BatchLimitFailure | QuotaManager.BatchLimitSuccess>;
-}
-/**
- * The quota manager module.
- * This manager can be used to manage and enforce usage quotas for different resources,
- * for instance limiting money spent on tokens, or for rate limiting purposes.
- *
- * For managing monetary quotas, it is advised to use a nano-scale amount system
- * (smallest unit integer accounting). See {@link Quota.to_nano} for converting to nano scale.
- */
-export declare namespace QuotaManager {
-    /**
-     * The constructor options of the {@link QuotaManager} class.
-     *
-     * @docs
-     */
-    interface Opts {
-        /** The parent server instance, used to create the database collection. */
-        server: Server;
-        /**s
-         * The options for initialized the collection.
-         * @warning
-         * Ensure the chosen collection name is unique for this quota manager when using multiple quota managers.
-         * Since there is only a single configurable `id` index field per quota.
-         * Therefore using multiple purpose specific quota managers is required.
-         * @warning
-         * The {@link Quota.interval} may not exceed the `ttl` duration, if passed.
-         */
-        collection: Pick<Collection.Opts<QuotaManager.Document>, "ttl" | "name">;
-        /**
-         * Options for handling encountered system errors.
-         * See {@link SystemError}.
-         */
-        system_error?: {
-            /**
-             * The collection used to save {@link SystemError}'s to.
-             * Defaults to {@link SystemError.collection}.
-             *
-             * @warning Ensure either {@link collection} or {@link SystemError.collection}
-             *          is defined. Otherwise system errors are not saved to the database.
-             */
-            collection?: Collection<SystemError.Document>;
-            /**
-             * The logger to use for creating system {@link SystemError}'s.
-             * Defaults to {@link SystemError.logger}.
-             */
-            logger?: SystemError.Logger;
-        };
-    }
-    /**
-     * The interface for a quota search query.
-     *
-     * @dev_note Ensure this remains a FLAT interface, or update spread copies to deep copies.
-     *
-     * @docs
-     */
-    interface Query {
-        /** The user id (index attribute). */
-        uid: string;
-        /** The quota id, e.g. "my-project" (index attribute). */
-        id: string;
-    }
-    /** Nested types for the {@link QuotaManager.Query} type. */
-    namespace Query {
-        /**
-         * Validate {@link QuotaManager.Query} at runtime.
-         * @returns An error message if the query is invalid, or undefined if it is valid.
-         */
-        function validate(query: Query): string | undefined;
-    }
-    /**
-     * Quota settings for managing costs.
-     * This interface can serves as a quota group which can be configured for account-wide, project-wide etc quotas.
-     *
-     * @dev_note Ensure this remains a FLAT interface, or update spread copies to deep copies.
-     *
-     * @docs
-     */
-    interface Quota {
-        /**
-         * The maximum amount of usage allowed.
-         * Allowed: positive finite floating number (decimals supported).
-         */
-        max: number;
-        /**
-         * The time interval in SECONDS for the quota; when this interval has passed the usage will be reset.
-         * Recommended to be an integer number of seconds.
-         * @note This may not exceed the collections `ttl` duration, if set.
-         */
-        interval: number;
-        /**
-         * The start timestamp in SECONDS of the quota interval period.
-         * This value is always persisted as an INTEGER (seconds since epoch).
-         */
-        start: number;
-        /**
-         * The current amount of usage.
-         * Allowed: finite floating number (decimals supported). Never persisted below 0.
-         */
-        usage: number;
-    }
-    /** Nested types for the {@link Quota} interface. */
-    namespace Quota {
-        /** The OpenAIQuery input options (excluding the usage & start attribute) */
-        type Opts = Omit<Quota, "usage" | "start">;
-        /** Nested types for the {@link Opts} interface. */
-        namespace Opts {
-            /** The schema to validate quota {@link Opts} */
-            const Schema: vlib.Schema.Entries.Opts;
-            /**
-             * Validate {@link Quota.Opts} at runtime.
-             * @returns An error message if the quota is invalid, or undefined if it is valid.
-             */
-            function validate(quota: Quota.Opts, collection: Collection<QuotaManager.Document>): string | undefined;
-        }
-        /**
-         * Convert `null | undefined` to `undefined` (no-op).
-         */
-        function to_nano(q: null | undefined, opts?: {
-            round?: SafeInt.Rounding;
-        }): undefined;
-        /**
-         * Convert a numeric amount to its nano-scale integer.
-         */
-        function to_nano(q: number, opts?: {
-            round?: SafeInt.Rounding;
-        }): number;
-        /**
-         * Convert quota options to nano-scale by scaling `max`; `interval` is preserved.
-         */
-        function to_nano(q: Quota.Opts, opts?: {
-            round?: SafeInt.Rounding;
-        }): Quota.Opts;
-    }
-    /** The OpenAIQuery quota document. */
-    type Document = Quota & Query;
-    /** Nested types for the {@link Document} type. */
-    namespace Document {
-        /** Input options for creating a {@link Document} record. */
-        type Opts = Quota.Opts & Query;
-        /** Nested types for the {@link Document.Opts} type. */
-        namespace Opts {
-            /**
-             * Validate {@link Document.Opts} at runtime.
-             * @returns An error message if the quota is invalid, or undefined if it is valid.
-             */
-            function validate(quota: QuotaManager.Document.Opts, collection: Collection<QuotaManager.Document>): string | undefined;
-        }
-    }
-    /**
-     * The listed quota from {@link QuotaManager.list}.
-     *
-     * @docs
-     */
-    interface ListedQuota {
-        /** The listed quota. */
-        quota: QuotaManager.Document;
-        /** The remaining usage left for this quota. */
-        remaining: number;
-        /** Percentage used for the quota. */
-        percentage_used: number;
-        /** Quota needs a reset, interval has expired. */
-        needs_reset: boolean;
-    }
-    /**
-     * The returned type of {@link QuotaManager.get_status}
-     *
-     * @docs
-     */
-    type GetStatusResult = {
-        found: false;
-        /** Diagnostic message. */
-        error: string;
-        /**
-         * The error reason.
-         * @note By default a {@link SystemError} is saved when the status is `system_error`.
-         */
-        reason: "invalid_query" | "not_found" | "system_error";
-    } | {
-        /** Indicates the quota was found. */
-        found: true;
-        /** The current quota (or a virtual reset view if the window expired). */
-        quota: QuotaManager.Document;
-        /** Remaining capacity in the active window (never negative). */
-        remaining: number;
-        /** Percentage of the window used, clamped to [0, 100]. */
-        percentage_used: number;
-        /** Whether the interval needs a reset (i.e., has expired). */
-        needs_reset: boolean;
-        /** Seconds until reset (0 when the window already expired). */
-        time_until_reset: number;
-    };
-    /**
-     * The parameter options for {@link limit} and {@link increment}
-     *
-     * @docs
-     */
-    interface LimitOpts {
-        /** The quota identifier arguments. */
-        query: Query;
-        /** The amount of usage to increment, this may be a negative amount, must it must be a finite number. */
-        requested_usage: number;
-        /** The quota document to create if it doesn't exist, if left undefined, the quota document must exist in the collection, or the validation will fail. */
-        upsert?: Quota.Opts;
-        /**
-         * The usage validation safety ratio, used to prevent over-usage, defaults to `1.0`.
-         *
-         * The validation will be applied as:
-         * `would_exceeded = (requested_usage * safety_ratio) + current.usage > current.max`
-         *
-         * The incrementation caused by the safety ratio is not saved to the database.
-         */
-        safety_ratio?: number;
-        /** Whether to perform the increment, defaults to `true`. */
-        perform_increment?: boolean;
-    }
-    /**
-     * The non allowed response of {@link limit}.
-     *
-     * @docs
-     */
-    interface LimitFailure {
-        /** Validation success indicator. */
-        success: false;
-        /**
-         * The limit failure status.
-         * @note By default a {@link SystemError} is saved when the status is `system_error`.
-         */
-        status: "not_found" | "exceeded" | "would_exceed" | "invalid_usage" | "system_error";
-        /** The error message. */
-        error: string;
-        /** The quota document, if available. */
-        quota?: QuotaManager.Document;
-        /** The remaining quota usage. */
-        remaining?: number;
-    }
-    /**
-     * The allowed response of {@link limit}.
-     *
-     * @docs
-     */
-    interface LimitSuccess {
-        /** Validation success indicator. */
-        success: true;
-        /** The operation status, kept for consistency. */
-        status: "success";
-        /** The returned quota document. */
-        quota: QuotaManager.Document;
-        /** The remaining quota usage. */
-        remaining: number;
-        /** Whether the quota was reset. */
-        was_reset: boolean;
-    }
-    /**
-     * The batch limit query and requested usage for {@link batch_limit}.
-     *
-     * @docs
-     */
-    interface BatchLimit {
-        /** The query identifying the quota */
-        query: Query;
-        /** The requested usage amount */
-        requested_usage: number;
-        /**
-         * The usage validation safety ratio, used to prevent over-usage, defaults to `1.0`.
-         *
-         * The validation will be applied as:
-         * `would_exceeded = (requested_usage * safety_ratio) + current.usage > current.max`
-         *
-         * The incrementation caused by the safety ratio is not saved to the database.
-         */
-        safety_ratio?: number;
-        /**
-         * The quota document to create if it doesn't exist, if left undefined, the quota document must exist in the collection, or the validation will fail.
-         * @dev_note We use `Quota.Opts` instead of `Document.Opts` so we can derive the query attrs from field `query`
-         */
-        upsert?: Quota.Opts;
-        /** Whether to enforce limit checks, defaults to `true`. */
-        check_limit?: boolean;
-        /** Whether to perform the increment, defaults to `true`. */
-        perform_increment?: boolean;
-    }
-    /**
-     * The batch limit failure response.
-     *
-     * @docs
-     */
-    interface BatchLimitFailure extends LimitFailure {
-        /** The failed query identifying the quota */
-        failed_query: Query;
-    }
-    /**
-     * The batch limit success response.
-     *
-     * @docs
-     */
-    interface BatchLimitSuccess {
-        /** Validation success indicator. */
-        success: true;
-        /** The operation status, kept for consistency. */
-        status: "success";
-        /** The individual results for each quota. */
-        results: LimitSuccess[];
-    }
-}