@usagekit/store 0.1.0 → 0.4.0

package/dist/memory/counters.d.ts

@@ -0,0 +1,33 @@
+import type { CountRequestInput, CountRequestResult, RequestCountsPage, RequestCountsQuery } from "@usagekit/core";
+import type { State } from "./state.js";
+/** Dimensions a request count can be grouped by. */
+export declare const requestCountDimensions: string[];
+/** Throws InvalidInput for a malformed count; every adapter calls it before writing. */
+export declare function validateCountRequest(i: CountRequestInput): void;
+/** Replay identity of a count: the whole input, pools sorted. */
+export declare const countIdentity: (i: CountRequestInput) => string;
+/**
+ * Counts are daily UTC buckets, so a window must start and end at UTC midnight; a narrower
+ * window would silently widen to whole days.
+ */
+export declare function validateRequestCountsQuery(q: RequestCountsQuery): void;
+/** One stored bucket: the counted fields and the UTC day. */
+export type CountBucket = {
+    namespace: string;
+    principal: string;
+    group: string;
+    connection: string;
+    pools: readonly string[];
+    day: string;
+    provider: string;
+    operation: string;
+    source: string;
+    state: CountRequestInput["state"];
+    count: bigint;
+};
+export declare const bucketOf: (i: CountRequestInput, now: Date) => Omit<CountBucket, "count">;
+export declare function bucketInScope(b: Omit<CountBucket, "count">, q: RequestCountsQuery): boolean;
+/** Groups buckets into rows ordered by dimension values in groupBy order, then state. */
+export declare function countRows(buckets: Iterable<CountBucket>, q: RequestCountsQuery, asOf: string): RequestCountsPage;
+export declare function countRequest(s: State, i: CountRequestInput): CountRequestResult;
+export declare function requestCounts(s: State, q: RequestCountsQuery): RequestCountsPage;

package/dist/memory/counters.js

@@ -0,0 +1,113 @@
+import { requestStates } from "@usagekit/core";
+import { canonical, copy, InvalidInput, key } from "./state.js";
+/** Dimensions a request count can be grouped by. */
+export const requestCountDimensions = ["provider", "operation", "connection", "source", "day"];
+const dayMs = 86400000;
+/** Throws InvalidInput for a malformed count; every adapter calls it before writing. */
+export function validateCountRequest(i) {
+    for (const [field, value] of [
+        ["commandId", i.commandId],
+        ["scope.namespace", i.scope?.namespace],
+        ["scope.principal", i.scope?.principal],
+        ["scope.connection", i.scope?.connection],
+        ["provider", i.provider],
+        ["operation", i.operation],
+    ])
+        if (typeof value !== "string" || !value.trim())
+            throw new InvalidInput(field, "empty string");
+    if (!requestStates.includes(i.state))
+        throw new InvalidInput("state", "unknown request state");
+}
+/** Replay identity of a count: the whole input, pools sorted. */
+export const countIdentity = (i) => canonical({ ...i, platformPools: [...(i.platformPools ?? [])].sort() });
+/**
+ * Counts are daily UTC buckets, so a window must start and end at UTC midnight; a narrower
+ * window would silently widen to whole days.
+ */
+export function validateRequestCountsQuery(q) {
+    const from = Date.parse(q.from), to = Date.parse(q.to);
+    if (!Number.isFinite(from) || !Number.isFinite(to) || from > to)
+        throw new InvalidInput("window", "invalid time interval");
+    if (from % dayMs !== 0 || to % dayMs !== 0)
+        throw new InvalidInput("window", "request counts use whole UTC days");
+    if (q.limit !== undefined && (!Number.isInteger(q.limit) || q.limit < 1 || q.limit > 1000))
+        throw new InvalidInput("limit", "must be between 1 and 1000");
+    if (q.groupBy.some((d) => !requestCountDimensions.includes(d)))
+        throw new InvalidInput("groupBy", "unknown request count dimension");
+}
+export const bucketOf = (i, now) => ({
+    namespace: i.scope.namespace,
+    principal: i.scope.principal,
+    group: i.scope.group ?? "",
+    connection: i.scope.connection,
+    pools: [...(i.platformPools ?? [])].sort(),
+    day: now.toISOString().slice(0, 10),
+    provider: i.provider,
+    operation: i.operation,
+    source: i.source,
+    state: i.state,
+});
+export function bucketInScope(b, q) {
+    if (b.namespace !== q.scope.namespace || (q.connection && b.connection !== q.connection))
+        return false;
+    const day = Date.parse(`${b.day}T00:00:00.000Z`);
+    if (day < Date.parse(q.from) || day >= Date.parse(q.to))
+        return false;
+    switch (q.scope.kind) {
+        case "namespace":
+            return true;
+        case "principal":
+            return b.principal === q.scope.principal;
+        case "group":
+            return b.group === q.scope.group;
+        case "platform_pool":
+            return b.pools.includes(q.scope.poolId);
+    }
+}
+/** Groups buckets into rows ordered by dimension values in groupBy order, then state. */
+export function countRows(buckets, q, asOf) {
+    const map = new Map();
+    for (const b of buckets) {
+        if (!bucketInScope(b, q))
+            continue;
+        const dimensions = {};
+        for (const d of q.groupBy)
+            dimensions[d] = b[d];
+        const order = [...q.groupBy.map((d) => dimensions[d]), b.state], k = canonical(order), prev = map.get(k);
+        map.set(k, { dimensions, state: b.state, count: (prev?.count ?? 0n) + b.count, order });
+    }
+    const sorted = [...map.values()].sort((a, b) => compare(a.order, b.order)), limit = q.limit ?? 1000;
+    return {
+        rows: sorted.slice(0, limit).map(({ dimensions, state, count }) => ({
+            dimensions,
+            state,
+            count,
+        })),
+        asOf,
+        truncated: sorted.length > limit,
+    };
+}
+function compare(a, b) {
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    return 0;
+}
+export function countRequest(s, i) {
+    validateCountRequest(i);
+    const commandKey = key(i.scope.namespace, i.commandId), identity = countIdentity(i), commands = (s.requestCommands ??= new Map()), previous = commands.get(commandKey);
+    if (previous !== undefined)
+        return previous === identity
+            ? { outcome: "counted", replayed: true }
+            : { outcome: "conflict", reason: "command_mismatch" };
+    if (s.operations.has(commandKey))
+        return { outcome: "conflict", reason: "command_mismatch" };
+    const bucket = bucketOf(i, s.clock.now()), buckets = (s.requestBuckets ??= new Map()), bucketKey = canonical(bucket);
+    buckets.set(bucketKey, { ...bucket, count: (buckets.get(bucketKey)?.count ?? 0n) + 1n });
+    commands.set(commandKey, identity);
+    return { outcome: "counted", replayed: false };
+}
+export function requestCounts(s, q) {
+    validateRequestCountsQuery(q);
+    return copy(countRows(s.requestBuckets?.values() ?? [], q, s.clock.now().toISOString()));
+}

package/dist/memory/memory-store.js

@@ -1,11 +1,14 @@
-import { aggregate, definedBudgets, applicableBudgets } from "./reads.js";
+import { aggregate, definedBudgets, applicableBudgets, listOperations } from "./reads.js";
 import { copy, find } from "./state.js";
+import { countRequest, requestCounts } from "./counters.js";
 import { reserve, intent, renew, settle, release, claim, expireReservations } from "./commands.js";
 export function createMemoryStore({ clock, budgets }) {
     const state = {
         clock,
         budgets,
         warnings: new Map(),
+        reserveAlerts: new Map(),
+        alerts: new Set(),
         leaseKinds: new Map(),
         commands: new Map(),
         cursors: new Map(),
@@ -22,7 +25,10 @@ export function createMemoryStore({ clock, budgets }) {
         settle: async (i) => settle(state, i),
         correct: async (i) => settle(state, i, true),
         releaseUndispatched: async (i) => release(state, i),
+        countRequest: async (i) => countRequest(state, i),
+        requestCounts: async (q) => requestCounts(state, q),
         aggregate: async (q) => aggregate(state, q),
+        listOperations: async (q) => listOperations(state, q),
         definedBudgets: async (q) => definedBudgets(state, q),
         applicableBudgets: async (q) => applicableBudgets(state, q),
     };

package/dist/memory/reads.d.ts

@@ -1,5 +1,7 @@
-import type { UsageQuery, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery } from "@usagekit/core";
+import type { UsageQuery, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery, OperationsQuery, OperationsPage } from "@usagekit/core";
 import type { State } from "./state.js";
 export declare const definedBudgets: (s: State, q: DefinedBudgetsQuery) => import("@usagekit/core").Budget[];
 export declare const applicableBudgets: (s: State, q: ApplicableBudgetsQuery) => import("@usagekit/core").BudgetStatus[];
 export declare function aggregate(s: State, q: UsageQuery): UsagePage;
+/** Mirrors aggregate: the first page fixes membership and order; pages return current records. */
+export declare function listOperations(s: State, q: OperationsQuery): OperationsPage;

package/dist/memory/reads.js

@@ -63,41 +63,50 @@ function rows(s, q) {
                     ? op.platformPools
                     : [""]
             : [""];
-        for (const pool of pools) {
-            const dimensions = {};
-            for (const dimension of q.groupBy) {
-                switch (dimension) {
-                    case "principal":
-                        dimensions[dimension] = op.scope.principal;
-                        break;
-                    case "connection":
-                        dimensions[dimension] = op.scope.connection;
-                        break;
-                    case "day":
-                        dimensions[dimension] = new Date(receipt.occurredAt).toISOString().slice(0, 10);
-                        break;
-                    case "access_credential":
-                        dimensions[dimension] = op.scope.accessCredential
-                            ? canonical([op.scope.accessCredential.kind, op.scope.accessCredential.id])
-                            : "";
-                        break;
-                    case "platform_pool":
-                        dimensions[dimension] = pool;
-                        break;
-                    default:
-                        dimensions[dimension] = op[dimension];
+        // Pool and tag rows explode per value; an operation without any contributes one empty row.
+        const tags = q.groupBy.includes("tag") && op.scope.tags?.length ? op.scope.tags : [""];
+        for (const pool of pools)
+            for (const tag of tags) {
+                const dimensions = {};
+                for (const dimension of q.groupBy) {
+                    switch (dimension) {
+                        case "principal":
+                            dimensions[dimension] = op.scope.principal;
+                            break;
+                        case "connection":
+                            dimensions[dimension] = op.scope.connection;
+                            break;
+                        case "day":
+                            dimensions[dimension] = new Date(receipt.occurredAt).toISOString().slice(0, 10);
+                            break;
+                        case "access_credential":
+                            dimensions[dimension] = op.scope.accessCredential
+                                ? canonical([op.scope.accessCredential.kind, op.scope.accessCredential.id])
+                                : "";
+                            break;
+                        case "platform_pool":
+                            dimensions[dimension] = pool;
+                            break;
+                        case "funding_source":
+                            dimensions[dimension] = op.fundingSource;
+                            break;
+                        case "tag":
+                            dimensions[dimension] = tag;
+                            break;
+                        default:
+                            dimensions[dimension] = op[dimension];
+                    }
                 }
+                const k = canonical([dimensions, op.fundingSource, op.costOwner]), prev = map.get(k), measurements = receipt.measurements.filter((m) => q.units.includes(m.unit));
+                map.set(k, {
+                    dimensions,
+                    fundingSource: op.fundingSource,
+                    costOwner: op.costOwner,
+                    measurements: combineMeasurements(prev?.measurements ?? [], measurements),
+                    cost: prev ? combineCost(prev.cost, receipt.cost) : copy(receipt.cost),
+                    unknownOperations: (prev?.unknownOperations ?? 0n) + (op.state === "pending" ? 1n : 0n),
+                });
             }
-            const k = canonical([dimensions, op.fundingSource, op.costOwner]), prev = map.get(k), measurements = receipt.measurements.filter((m) => q.units.includes(m.unit));
-            map.set(k, {
-                dimensions,
-                fundingSource: op.fundingSource,
-                costOwner: op.costOwner,
-                measurements: combineMeasurements(prev?.measurements ?? [], measurements),
-                cost: prev ? combineCost(prev.cost, receipt.cost) : copy(receipt.cost),
-                unknownOperations: (prev?.unknownOperations ?? 0n) + (op.state === "pending" ? 1n : 0n),
-            });
-        }
     }
     return [...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, r]) => r);
 }
@@ -129,3 +138,48 @@ export function aggregate(s, q) {
     }
     return page;
 }
+const byCreation = (a, b) => a.createdAt === b.createdAt
+    ? a.operationId < b.operationId
+        ? -1
+        : 1
+    : Date.parse(a.createdAt) - Date.parse(b.createdAt);
+/** Mirrors aggregate: the first page fixes membership and order; pages return current records. */
+export function listOperations(s, q) {
+    const { cursor, ...query } = q;
+    const identity = canonical(query), cursors = (s.operationCursors ??= new Map());
+    let snapshot;
+    if (cursor) {
+        snapshot = cursors.get(cursor);
+        if (!snapshot || snapshot.query !== identity)
+            throw new InvalidInput("cursor", "unknown cursor or query mismatch");
+    }
+    else {
+        const from = Date.parse(q.from), to = Date.parse(q.to);
+        const members = [...s.operations.values()]
+            .filter((op) => {
+            const created = Date.parse(op.createdAt);
+            return (inScope(op, q) &&
+                created >= from &&
+                created < to &&
+                (q.states === undefined || q.states.includes(op.state)));
+        })
+            .sort(byCreation);
+        snapshot = {
+            query: identity,
+            keys: members.map((op) => canonical([op.scope.namespace, op.operationId])),
+            asOf: s.clock.now().toISOString(),
+            watermark: crypto.randomUUID(),
+            offset: 0,
+        };
+    }
+    const end = snapshot.offset + (q.limit ?? 1000), page = {
+        operations: snapshot.keys.slice(snapshot.offset, end).map((k) => copy(s.operations.get(k))),
+        asOf: snapshot.asOf,
+        watermark: snapshot.watermark,
+    };
+    if (end < snapshot.keys.length) {
+        page.nextCursor = crypto.randomUUID();
+        cursors.set(page.nextCursor, { ...snapshot, offset: end });
+    }
+    return page;
+}

package/dist/memory/state.d.ts

@@ -1,9 +1,10 @@
 import type { DispatchGrant } from "@usagekit/core";
 import type { UsageRow } from "@usagekit/core";
 import type { SettleResult, ReleaseResult } from "@usagekit/core";
-import type { AllowanceExceeded } from "@usagekit/core";
+import type { AllowanceExceeded, BudgetAlertCrossed } from "@usagekit/core";
 import type { Budget, Operation, ReserveInput, OperationRef, Quantity } from "@usagekit/core";
 import type { Clock } from "../clock.js";
+import type { CountBucket } from "./counters.js";
 export declare class InvalidInput extends Error {
     readonly field: string;
     readonly reason: string;
@@ -12,7 +13,10 @@ export declare class InvalidInput extends Error {
 export declare const copy: <T>(value: T) => T;
 export declare function canonical(value: unknown): string;
 export declare const key: (namespace: string, id: string) => string;
+/** Reserve identity: diagnostic ids, estimate provenance and attribution tags are not semantic. */
 export declare function semantics(i: ReserveInput): string;
+/** Sorted tags on the stored input, or an InvalidInput when the list breaks the tag rules. */
+export declare function withNormalizedTags(i: ReserveInput): ReserveInput;
 export declare const maxMoneyUnits: bigint;
 export declare function validateQuantity(q: Quantity): void;
 export type State = {
@@ -28,6 +32,14 @@ export type State = {
         watermark: string;
         offset: number;
     }>;
+    /** Operation listing snapshots: membership and order fixed by the first page. */
+    operationCursors?: Map<string, {
+        query: string;
+        keys: string[];
+        asOf: string;
+        watermark: string;
+        offset: number;
+    }>;
     clock: Clock;
     budgets: Budget[];
     operations: Map<string, Operation>;
@@ -38,5 +50,13 @@ export type State = {
     }>;
     leaseKinds: Map<string, "lease" | "recovery">;
     warnings: Map<string, readonly AllowanceExceeded[]>;
+    /** Crossings each reserve reported, replayed verbatim. */
+    reserveAlerts: Map<string, readonly BudgetAlertCrossed[]>;
+    /** Recorded crossings keyed by namespace, budget id, epoch and threshold. */
+    alerts: Set<string>;
+    /** Request counter: replay identities by namespace and command id. */
+    requestCommands?: Map<string, string>;
+    /** Request counter: daily buckets keyed by their canonical fields. */
+    requestBuckets?: Map<string, CountBucket>;
 };
 export declare function find(s: State, ref: OperationRef): Operation | null;

package/dist/memory/state.js

@@ -1,3 +1,4 @@
+import { normalizeTags } from "@usagekit/core";
 export class InvalidInput extends Error {
     field;
     reason;
@@ -22,14 +23,26 @@ export function canonical(value) {
     return JSON.stringify(value) ?? "null";
 }
 export const key = (namespace, id) => canonical([namespace, id]);
+/** Reserve identity: diagnostic ids, estimate provenance and attribution tags are not semantic. */
 export function semantics(i) {
-    const { correlationId: _, parentOperationId: __, ...rest } = i;
+    const { correlationId: _, parentOperationId: __, estimateSource: _source, providerPriceVersion: _priceVersion, scope, ...rest } = i;
+    const { tags: ___, ...scopeIdentity } = scope;
     return canonical({
         ...rest,
+        scope: scopeIdentity,
         estimate: [...i.estimate].sort((a, b) => a.unit.localeCompare(b.unit)),
         platformPools: [...(i.platformPools ?? [])].sort(),
     });
 }
+/** Sorted tags on the stored input, or an InvalidInput when the list breaks the tag rules. */
+export function withNormalizedTags(i) {
+    if (i.scope.tags === undefined)
+        return i;
+    const tags = normalizeTags(i.scope.tags);
+    if (!tags)
+        throw new InvalidInput("scope.tags", "1 to 16 unique tags matching the tag pattern");
+    return { ...i, scope: { ...i.scope, tags } };
+}
 export const maxMoneyUnits = 2n ** 63n - 1n;
 export function validateQuantity(q) {
     if (typeof q.value !== "bigint" ||

package/dist/reference.d.ts

@@ -1,6 +1,6 @@
 /** Synchronous reference rules shared by adapters inside their own atomic transactions. */
 export { reserve, intent, renew, claim, settle, release, expireReservations, } from "./memory/commands.js";
-export { aggregate, definedBudgets, applicableBudgets } from "./memory/reads.js";
+export { aggregate, definedBudgets, applicableBudgets, listOperations } from "./memory/reads.js";
 export { copy, find, key, canonical, InvalidInput } from "./memory/state.js";
 export type { State } from "./memory/state.js";
-export { plus, effective, currentBudgets } from "./memory/admission.js";
+export { plus, effective, currentBudgets, validateBudget, crossing, reachedAlerts, alertKey, alertThreshold, } from "./memory/admission.js";

package/dist/reference.js

@@ -1,5 +1,5 @@
 /** Synchronous reference rules shared by adapters inside their own atomic transactions. */
 export { reserve, intent, renew, claim, settle, release, expireReservations, } from "./memory/commands.js";
-export { aggregate, definedBudgets, applicableBudgets } from "./memory/reads.js";
+export { aggregate, definedBudgets, applicableBudgets, listOperations } from "./memory/reads.js";
 export { copy, find, key, canonical, InvalidInput } from "./memory/state.js";
-export { plus, effective, currentBudgets } from "./memory/admission.js";
+export { plus, effective, currentBudgets, validateBudget, crossing, reachedAlerts, alertKey, alertThreshold, } from "./memory/admission.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/store",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Atomic store commands, reference store and conformance tests.",
@@ -31,7 +31,7 @@
     "prepack": "node ../../scripts/package-license.mjs"
   },
   "dependencies": {
-    "@usagekit/core": "0.1.0"
+    "@usagekit/core": "0.4.0"
   },
   "sideEffects": false,
   "publishConfig": {