@schematichq/schematic-typescript-node 1.6.1 → 1.6.3

package/dist/credits/check.d.ts

@@ -33,7 +33,7 @@ export interface CreditCheckDeps {
  *      check. Otherwise `creditId` + `consumptionRate` + `eventSubtype` come
  *      straight off the entitlement — no structural flag scan.
  *   2. Acquire (or reuse) a lease for `(company, creditId)`.
- *   3. Try to reserve `quantity × consumptionRate` from the lease.
+ *   3. Try to reserve `ceil(quantity) × consumptionRate` from the lease.
  *   4. Run the WASM rules engine against a substituted company snapshot
  *      (`credit_balances[creditId] = lease.localRemaining` *before* the
  *      reservation we just made was debited), gating with `credit_cost` so the
@@ -45,9 +45,14 @@ export declare function checkWithLease(deps: CreditCheckDeps, key: string, evalC
  * Build the preflight options envelope for a client-side rules evaluation.
  * With an `eventSubtype` the quantity goes out as the `event_usage` pair so
  * the engine matches it to the subtype's condition; without one it goes out
- * as the generic `usage` knob. Exported so `client.check`'s fallback path can
- * thread the same preflight through a plain flag check — any client-side
- * evaluation (datastream, replicator) honors it even when the lease path
- * can't run.
+ * as the generic `usage` knob. Exported so `client.check`'s fallback path and
+ * the server-mode check-and-reserve body can thread the same preflight — any
+ * evaluation path honors it even when the lease path can't run.
+ *
+ * The quantity rounds up here, once, so every consumer of this envelope asks
+ * the same whole-unit question: the engine takes an integer, the REST body
+ * takes an integer, and the settling Track event bills `ceil(actual)`. A
+ * preflight is an upper bound, so rounding up is also the only safe direction
+ * — the check must not pass on less usage than the action is about to record.
  */
 export declare function buildPreflightOptions(options: CheckOptions): CheckFlagOptions | undefined;

package/dist/credits/index.d.ts

@@ -1,7 +1,7 @@
-export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore } from "./lease-store";
+export { LeaseStore, leaseKey, type LeaseEntry, type ILeaseStore, type ReserveResult } from "./lease-store";
 export { ReservationStore, type IReservationStore } from "./reservation-store";
-export { CreditLeaseManager } from "./lease-manager";
+export { CreditLeaseManager, settleWithin, unrefTimer } from "./lease-manager";
 export { RedisLeaseStore } from "./redis-lease-store";
 export { RedisReservationStore } from "./redis-reservation-store";
-export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, MAX_RESERVATION_TTL_MS, RESERVATION_TTL_SKEW_ALLOWANCE_MS, } from "./types";
+export { DEFAULT_LEASE_DURATION_MS, DEFAULT_LEASE_SIZE, DEFAULT_LOW_WATER_MARK, DEFAULT_PREWARM_POLL_INTERVAL_MS, DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS, DEFAULT_RESERVATION_TTL_MS, DEFAULT_SWEEP_INTERVAL_MS, MAX_RESERVATION_TTL_MS, RESERVATION_TTL_SKEW_ALLOWANCE_MS, SHUTDOWN_DRAIN_TIMEOUT_MS, } from "./types";
 export type { CreditLeaseConfig, CreditLeaseMode, ResolvedLeaseConfig, Reservation, CheckOptions, CheckResult, OnAcquireFailure, TrackWithReservationOptions, } from "./types";

package/dist/credits/lease-manager.d.ts

@@ -2,6 +2,15 @@ import type { CreditsClient } from "../api/resources/credits/client/Client";
 import type { Logger } from "../logger";
 import { type ILeaseStore, type LeaseEntry } from "./lease-store";
 import { type CreditLeaseConfig, type ResolvedLeaseConfig } from "./types";
+/** Drop a timer's hold on the event loop where the runtime has one (Node). */
+export declare function unrefTimer(timer: ReturnType<typeof setTimeout>): void;
+/**
+ * Await `promises`, giving up after `timeoutMs`. Reports whether everything
+ * landed, so a caller winding down can say what it is abandoning. Abandoned
+ * work is not cancelled — promises have no cancellation — it just stops being
+ * waited on.
+ */
+export declare function settleWithin(promises: Promise<unknown>[], timeoutMs: number): Promise<boolean>;
 /**
  * Owns the lifecycle of `credit_lease` rows for a single client: acquire on
  * first use or after expiry, extend when the local view dips below the low
@@ -20,6 +29,8 @@ export declare class CreditLeaseManager {
     private readonly config;
     private readonly inflightAcquire;
     private readonly inflightExtend;
+    private readonly background;
+    private stopped;
     constructor(opts: {
         creditsClient: CreditsClient;
         leaseStore: ILeaseStore;
@@ -48,12 +59,71 @@ export declare class CreditLeaseManager {
      *     that figure (a single check just failed a reserve for that many
      *     credits — extend opportunistically instead of waiting for the next
      *     sub-watermark check).
+     * A caller arriving while an extend is in flight joins it. If its own
+     * shortfall is larger than what that extend asked for, it waits the flight
+     * out and then issues exactly one follow-up extend for the remaining
+     * difference — otherwise it would inherit a tranche-sized ask and fail its
+     * post-extend retry with credits still sitting on the server. A flight it
+     * finds on the way back is only joined if that one covers the shortfall
+     * too; a smaller one is waited out, never inherited.
      * Returns the in-flight promise so callers can await it or fire-and-forget.
      * Never rejects (it is often fire-and-forget — a rejection would surface
      * as an unhandled promise rejection).
      */
-    maybeExtendInBackground(companyId: string, creditTypeId: string, requiredCredits?: number, requestOptions?: CreditsClient.RequestOptions): Promise<LeaseEntry | undefined>;
+    maybeExtendInBackground(companyId: string, creditTypeId: string, requiredCredits?: number, requestOptions?: CreditsClient.RequestOptions, joinDeadlineMs?: number): Promise<LeaseEntry | undefined>;
+    private extendIfNeeded;
+    /** When a joiner's wait on a shared flight runs out, or undefined for no cap. */
+    private joinDeadline;
+    /**
+     * Await a flight somebody else is running, giving up at `deadline`. Giving
+     * up abandons only our wait: the flight keeps running for the callers still
+     * on it, and whatever it installs is there for our next check to read.
+     */
+    private joinWithin;
+    /**
+     * Read the slot, reporting `undefined` when the read fails or the lease is
+     * absent or expired. An expired lease is never extended: the server treats
+     * it as released (its remainder already refunded to the company balance),
+     * so the right move is a fresh acquire, which the next check's
+     * `acquireIfNeeded` performs. Extending would at best waste a wire call and
+     * at worst resurrect a stale local row.
+     */
+    private readLiveLease;
+    /** Whether `entry` sits low enough to warrant an extend. */
+    private needsExtend;
+    /**
+     * Register and run an extend as the slot's in-flight one. The cleanup is
+     * identity-guarded rather than an unconditional `delete`: a joiner whose
+     * shortfall outran this flight registers a follow-up for the same key, and
+     * this flight's `finally` must not evict it.
+     */
+    private startExtend;
+    /**
+     * Re-read the slot now that this flight owns it, and extend only if the
+     * fresh row still warrants one. The row that decided this extend was read
+     * before the flight was registered, so an extend that landed in that gap,
+     * clearing its own flight on the way out, would otherwise be followed by a
+     * second extend, under a new idempotency key, for a lease it already topped
+     * up. The registered `requestedAdditional` stands: a joiner compares its
+     * shortfall against that figure, so the wire body has to carry it.
+     */
+    private recheckAndExtend;
     private extend;
+    /** Hold a reference to unawaited work so `drain()` can wait it out. */
+    private track;
+    /**
+     * Refuse new lease work. Idempotent, and paired with `drain()`: stopping
+     * first is what makes the drain terminate, since nothing can enqueue
+     * behind it.
+     */
+    stop(): void;
+    /**
+     * Wait out lease work already on the wire, so a close releases what that
+     * work installs instead of orphaning it. Bounded: whatever has not landed
+     * by `timeoutMs` is abandoned rather than stalling the caller's shutdown,
+     * and the credits it holds fall back to server-side expiry.
+     */
+    drain(timeoutMs?: number): Promise<void>;
     /**
      * Release every live lease held in the store. ONLY safe when the store is
      * per-process (in-memory): those leases are exclusively this process's, so
@@ -63,6 +133,8 @@ export declare class CreditLeaseManager {
      * drawing on the same leases — and is excluded by the `list` capability
      * check (only the in-memory store implements it). Best-effort: failures
      * are logged and the lease falls back to server-side expiry.
+     * Bounded by `timeoutMs`, so a store or wire call that never lands cannot
+     * hold a closing client open; whatever is abandoned expires server-side.
      */
-    releaseAllLocalLeases(): Promise<void>;
+    releaseAllLocalLeases(timeoutMs?: number): Promise<void>;
 }

package/dist/credits/lease-store.d.ts

@@ -21,6 +21,14 @@ export interface LeaseEntry {
     localRemainingCredits: number;
     expiresAt: Date;
 }
+/**
+ * Outcome of a successful `tryReserve`: the post-debit balance plus the ID of
+ * the lease the credits actually came out of.
+ */
+export interface ReserveResult {
+    balance: number;
+    leaseId: string;
+}
 /** Backing-store contract shared by `LeaseStore` (in-memory) and `RedisLeaseStore` (shared). */
 export interface ILeaseStore {
     get(companyId: string, creditTypeId: string): Promise<LeaseEntry | undefined> | LeaseEntry | undefined;
@@ -65,15 +73,23 @@ export interface ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Atomically check-and-debit `credits` from the lease's remaining balance.
-     * Returns the post-debit `localRemainingCredits` on success, or `null` if
-     * there is no live lease, the balance is insufficient, or `credits` is not
-     * a finite non-negative number (NaN must never reach the debit — it slips
-     * through every numeric comparison and would poison the balance into
-     * allowing everything). Returning the balance rather than a boolean lets
-     * the caller derive the pre-debit figure (`returned + credits`) without a
-     * follow-up read.
+     * Returns the post-debit `localRemainingCredits` together with the
+     * `leaseId` the debit landed on, or `null` if there is no live lease, the
+     * balance is insufficient, or `credits` is not a finite non-negative
+     * number (NaN must never reach the debit — it slips through every numeric
+     * comparison and would poison the balance into allowing everything).
+     * Returning the balance rather than a boolean lets the caller derive the
+     * pre-debit figure (`returned + credits`) without a follow-up read.
+     *
+     * The debit is NOT keyed by lease ID: it charges whichever lease occupies
+     * the slot at that moment, which need not be the one the caller's acquire
+     * handed back — the slot's lease can be replaced in between (by the
+     * sweeper, or by a sibling pod on a shared backend). The caller MUST
+     * therefore pin its reservation to the returned `leaseId`, never to the
+     * acquired one: the settle refund, the sweep refund, and the Track event's
+     * `lease_id` all have to name the lease that was actually charged.
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits to the slot's lease balance (clamped at `grantedAmount`).
      * When `leaseId` is supplied, the refund applies ONLY if the slot still
@@ -126,10 +142,10 @@ export declare class LeaseStore implements ILeaseStore {
     drop(companyId: string, creditTypeId: string): Promise<void>;
     /**
      * Attempt to reserve `credits` from the local remaining balance.
-     * Returns the post-debit balance on success, `null` if there isn't enough
-     * remaining (see `ILeaseStore.tryReserve`).
+     * Returns the post-debit balance and the charged lease's ID on success,
+     * `null` if there isn't enough remaining (see `ILeaseStore.tryReserve`).
      */
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     /**
      * Refund credits back to the local balance (capped at grantedAmount).
      * When `leaseId` is given, the refund is dropped if the slot now holds a

package/dist/credits/redis-lease-store.d.ts

@@ -1,5 +1,5 @@
 import type { RedisClient } from "../cache/redis";
-import { type ILeaseStore, type LeaseEntry } from "./lease-store";
+import { type ILeaseStore, type LeaseEntry, type ReserveResult } from "./lease-store";
 /**
  * Redis-backed lease store. One hash per `(companyId, creditTypeId)` slot, with
  * atomic mutations via single-key Lua scripts so it stays correct on both
@@ -25,6 +25,6 @@ export declare class RedisLeaseStore implements ILeaseStore {
     replace(entry: Omit<LeaseEntry, "localRemainingCredits">): Promise<boolean>;
     extend(companyId: string, creditTypeId: string, grantedAmount: number, newExpiresAt?: Date, leaseId?: string): Promise<void>;
     drop(companyId: string, creditTypeId: string): Promise<void>;
-    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<number | null>;
+    tryReserve(companyId: string, creditTypeId: string, credits: number): Promise<ReserveResult | null>;
     refund(companyId: string, creditTypeId: string, credits: number, leaseId?: string): Promise<void>;
 }

package/dist/credits/types.d.ts

@@ -20,6 +20,7 @@ export declare const DEFAULT_LOW_WATER_MARK: number;
 export declare const DEFAULT_SWEEP_INTERVAL_MS: number;
 export declare const DEFAULT_PREWARM_RESOLVE_TIMEOUT_MS: number;
 export declare const DEFAULT_PREWARM_POLL_INTERVAL_MS: number;
+export declare const SHUTDOWN_DRAIN_TIMEOUT_MS: number;
 /**
  * Where a credit hold lives for a `check()` that passes `usage`.
  * - `client`: local leases over DataStream — the SDK acquires a tranche of