@voltro/kv 0.85.0 → 0.87.0

package/dist/hot-contract.d.ts

@@ -0,0 +1,297 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Option } from 'effect';
+import { Schema } from 'effect';
+import { Stream } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+/** Shared deterministic transition. No clock, store, socket or timer access. */
+export declare const applyHotOperations: (state: Map<string, HotEntry>, ops: ReadonlyArray<HotOp>, now: number) => ReadonlyArray<unknown>;
+
+/** Unicode scalar order matches Redis's UTF-8 byte order, including astral characters. */
+export declare const compareHotMembers: (a: string, b: string) => number;
+
+/** Consumers choose an explicit read fallback or preserve an unavailable failure. */
+declare type ConnectionUnavailablePolicy = 'degrade' | 'fail';
+
+/** Pure quota math shared by memory, database and HotStore consumers. */
+export declare const consumeHotRateLimit: (previous: HotRateLimitState | undefined, config: HotRateLimitConfig, nowMs: number) => HotRateLimitTransition;
+
+export declare interface HotBucketConfig {
+    readonly capacity: number;
+    readonly refillPerSec: number;
+}
+
+export declare interface HotBucketResult {
+    readonly allowed: boolean;
+    readonly remaining: number;
+    readonly retryAfterMs: number;
+}
+
+export declare interface HotCounterOptions extends HotTtl {
+    readonly max?: number;
+}
+
+export declare type HotEntry = HotValue & {
+    expiresAt: number;
+};
+
+/** Ephemeral data failures. SQL remains the durable source of truth. */
+export declare class HotError extends HotError_base {
+}
+
+declare const HotError_base: Schema.Class<HotError, Schema.TaggedStruct<"HotError", {
+    readonly operation: Schema.String;
+    readonly key: Schema.String;
+    readonly reason: Schema.Literals<readonly ["invalid", "wrongType", "limit", "unavailable"]>;
+}>, YieldableError>;
+
+export declare interface HotMember {
+    readonly member: string;
+    readonly score: number;
+}
+
+/** Operations accepted by an atomic batch. A batch cannot contain a scan. */
+export declare type HotOp = {
+    readonly op: 'zadd';
+    readonly key: string;
+    readonly members: ReadonlyArray<HotMember>;
+    readonly options?: HotZaddOptions;
+} | {
+    readonly op: 'zrem';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+} | {
+    readonly op: 'zrank';
+    readonly key: string;
+    readonly member: string;
+    readonly order: HotOrder;
+} | {
+    readonly op: 'zscore';
+    readonly key: string;
+    readonly member: string;
+} | {
+    readonly op: 'zrange';
+    readonly key: string;
+    readonly range: HotRange;
+    readonly order: HotOrder;
+    readonly options?: Pick<HotRangeOptions, 'limit'>;
+} | {
+    readonly op: 'zcard';
+    readonly key: string;
+} | {
+    readonly op: 'zremRange';
+    readonly key: string;
+    readonly range: HotRange;
+} | {
+    readonly op: 'incrBy';
+    readonly key: string;
+    readonly delta: number;
+    readonly options?: HotCounterOptions;
+} | {
+    readonly op: 'tokenBucket';
+    readonly key: string;
+    readonly config: HotBucketConfig;
+    readonly cost: number;
+} | {
+    readonly op: 'rateLimit';
+    readonly key: string;
+    readonly config: HotRateLimitConfig;
+    readonly nowMs?: number;
+} | {
+    readonly op: 'hset';
+    readonly key: string;
+    readonly fields: Readonly<Record<string, string>>;
+    readonly options?: HotTtl;
+} | {
+    readonly op: 'hget';
+    readonly key: string;
+    readonly field: string;
+} | {
+    readonly op: 'hgetAll';
+    readonly key: string;
+} | {
+    readonly op: 'hdel';
+    readonly key: string;
+    readonly fields: ReadonlyArray<string>;
+} | {
+    readonly op: 'sadd';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+    readonly options?: HotTtl;
+} | {
+    readonly op: 'srem';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+} | {
+    readonly op: 'smembers';
+    readonly key: string;
+} | {
+    readonly op: 'sismember';
+    readonly key: string;
+    readonly member: string;
+} | {
+    readonly op: 'setNx';
+    readonly key: string;
+    readonly value: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'compareDelete';
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly op: 'compareExpire';
+    readonly key: string;
+    readonly value: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'expire';
+    readonly key: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'delete';
+    readonly key: string;
+};
+
+export declare type HotOrder = 'asc' | 'desc';
+
+export declare type HotRange = {
+    readonly byRank: readonly [number, number];
+} | {
+    readonly byScore: readonly [number, number];
+};
+
+export declare interface HotRangeOptions extends HotReadOptions {
+    readonly limit?: number;
+}
+
+export declare interface HotRateLimitConfig {
+    readonly algorithm: 'fixed-window' | 'sliding-window' | 'token-bucket';
+    readonly limit: number;
+    readonly windowMs: number;
+    readonly burst: number;
+}
+
+export declare interface HotRateLimitResult extends HotBucketResult {
+    readonly resetAtMs: number;
+}
+
+export declare type HotRateLimitState = {
+    readonly kind: 'fixed';
+    readonly windowStart: number;
+    readonly count: number;
+} | {
+    readonly kind: 'sliding';
+    readonly currStart: number;
+    readonly currCount: number;
+    readonly prevCount: number;
+} | {
+    readonly kind: 'token';
+    readonly tokens: number;
+    readonly lastRefill: number;
+};
+
+export declare interface HotRateLimitTransition {
+    readonly state: HotRateLimitState;
+    readonly decision: HotRateLimitResult;
+}
+
+/** Default reads use the primary. Eventual reads may observe a replica. */
+export declare interface HotReadOptions {
+    readonly consistency?: 'primary' | 'eventual';
+}
+
+export declare class HotStore extends HotStore_base {
+}
+
+declare const HotStore_base: Context.ServiceClass<HotStore, "@voltro/HotStore", HotStoreShape>;
+
+/** Backends return JSON-compatible results; the public read methods lift misses to Option. */
+export declare const hotStoreFromRunner: (run: (operations: ReadonlyArray<HotOp>, options?: HotReadOptions) => Effect.Effect<ReadonlyArray<unknown>, HotError>, scanPrefix: (prefix: string) => Stream.Stream<string, HotError>, capabilities: HotStoreShape["capabilities"]) => HotStoreShape;
+
+/** Only non-mutating, single-key reads; no leases, quota consumption, batch or scan. */
+export declare type HotStoreReadShape = Pick<HotStoreShape, 'zrank' | 'zscore' | 'zrange' | 'zcard' | 'hget' | 'hgetAll' | 'smembers' | 'sismember'>;
+
+export declare interface HotStoreShape {
+    readonly zadd: (key: string, members: ReadonlyArray<HotMember>, options?: HotZaddOptions) => Effect.Effect<void, HotError>;
+    readonly zrem: (key: string, members: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly zrank: (key: string, member: string, order: HotOrder, options?: HotReadOptions) => Effect.Effect<Option.Option<number>, HotError>;
+    readonly zscore: (key: string, member: string, options?: HotReadOptions) => Effect.Effect<Option.Option<number>, HotError>;
+    readonly zrange: (key: string, range: HotRange, order: HotOrder, options?: HotRangeOptions) => Effect.Effect<ReadonlyArray<HotMember>, HotError>;
+    readonly zcard: (key: string, options?: HotReadOptions) => Effect.Effect<number, HotError>;
+    readonly zremRange: (key: string, range: HotRange) => Effect.Effect<number, HotError>;
+    readonly incrBy: (key: string, delta: number, options?: HotCounterOptions) => Effect.Effect<number, HotError>;
+    readonly tokenBucket: (key: string, config: HotBucketConfig, cost?: number) => Effect.Effect<HotBucketResult, HotError>;
+    /** Atomically check and consume one request. nowMs is trusted server/test time. */
+    readonly rateLimit: (key: string, config: HotRateLimitConfig, nowMs?: number) => Effect.Effect<HotRateLimitResult, HotError>;
+    readonly hset: (key: string, fields: Readonly<Record<string, string>>, options?: HotTtl) => Effect.Effect<void, HotError>;
+    readonly hget: (key: string, field: string, options?: HotReadOptions) => Effect.Effect<Option.Option<string>, HotError>;
+    readonly hgetAll: (key: string, options?: HotReadOptions) => Effect.Effect<Readonly<Record<string, string>>, HotError>;
+    readonly hdel: (key: string, fields: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly sadd: (key: string, members: ReadonlyArray<string>, options?: HotTtl) => Effect.Effect<number, HotError>;
+    readonly srem: (key: string, members: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly smembers: (key: string, options?: HotReadOptions) => Effect.Effect<ReadonlyArray<string>, HotError>;
+    readonly sismember: (key: string, member: string, options?: HotReadOptions) => Effect.Effect<boolean, HotError>;
+    readonly setNx: (key: string, value: string, ttlMs: number) => Effect.Effect<boolean, HotError>;
+    /** Atomically delete a setNx lease only while its value matches. Missing/mismatch returns false. */
+    readonly compareDelete: (key: string, value: string) => Effect.Effect<boolean, HotError>;
+    /** Atomically reset a matching setNx lease's TTL. Other structures fail with wrongType. */
+    readonly compareExpire: (key: string, value: string, ttlMs: number) => Effect.Effect<boolean, HotError>;
+    readonly expire: (key: string, ttlMs: number) => Effect.Effect<void, HotError>;
+    readonly delete: (key: string) => Effect.Effect<boolean, HotError>;
+    readonly scanPrefix: (prefix: string) => Stream.Stream<string, HotError>;
+    /** Isolated batch. Arguments are validated first. Like Redis MULTI, a backend
+     * need not roll back commands preceding a server-side execution failure. */
+    readonly multi: (operations: ReadonlyArray<HotOp>) => Effect.Effect<ReadonlyArray<unknown>, HotError>;
+    readonly capabilities: {
+        readonly atomicMulti: boolean;
+        readonly crossNode: boolean;
+        readonly persistent: boolean;
+    };
+}
+
+export declare interface HotTtl {
+    readonly ttlMs?: number;
+}
+
+export declare type HotValue = {
+    readonly kind: 'z';
+    readonly values: Map<string, number>;
+} | {
+    readonly kind: 'h';
+    readonly values: Map<string, string>;
+} | {
+    readonly kind: 's';
+    readonly values: Set<string>;
+} | {
+    readonly kind: 'counter';
+    value: number;
+} | {
+    readonly kind: 'lease';
+    readonly value: string;
+} | {
+    readonly kind: 'bucket';
+    tokens: number;
+    updatedAt: number;
+} | {
+    readonly kind: 'rateLimit';
+    readonly state: HotRateLimitState;
+};
+
+export declare interface HotZaddOptions extends HotTtl {
+    readonly mode?: 'set' | 'max' | 'min' | 'incr';
+}
+
+/** One read callback invocation; only a typed unavailable error may select the explicit fallback.
+ * Never use this boundary in a Room tick or for a write/rebuild. */
+export declare const readHotStoreWithFallback: <A, E, R, R2>(input: {
+    readonly store: HotStoreShape;
+    readonly onUnavailable: ConnectionUnavailablePolicy;
+    readonly read: (store: HotStoreReadShape) => Effect.Effect<A, HotError, R>;
+    readonly fallback: () => Effect.Effect<A, E, R2>;
+}) => Effect.Effect<A, HotError | E, R | R2>;
+
+/** Common argument validation, before a backend mutates anything. */
+export declare const validateHotOp: (op: HotOp) => void;
+
+export { }

package/dist/hot-contract.js

@@ -0,0 +1,18 @@
+import { consumeHotRateLimit as e } from "./hotRateLimit.js";
+import { hotStoreFromRunner as t, validateHotOp as n } from "./hotOperations.js";
+import { applyHotOperations as r, compareHotMembers as i } from "./hotState.js";
+import { readHotStoreWithFallback as a } from "./hotReadAvailability.js";
+import { Context as o, Schema as s } from "effect";
+//#region src/HotStore.ts
+var c = class extends s.TaggedError()("HotError", {
+	operation: s.String,
+	key: s.String,
+	reason: s.Literals([
+		"invalid",
+		"wrongType",
+		"limit",
+		"unavailable"
+	])
+}) {}, l = class extends o.Service()("@voltro/HotStore") {};
+//#endregion
+export { c as HotError, l as HotStore, r as applyHotOperations, i as compareHotMembers, e as consumeHotRateLimit, t as hotStoreFromRunner, a as readHotStoreWithFallback, n as validateHotOp };

package/dist/hot-testing.d.ts

@@ -0,0 +1,229 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Option } from 'effect';
+import { Schema } from 'effect';
+import { Stream } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+declare interface HotBucketConfig {
+    readonly capacity: number;
+    readonly refillPerSec: number;
+}
+
+declare interface HotBucketResult {
+    readonly allowed: boolean;
+    readonly remaining: number;
+    readonly retryAfterMs: number;
+}
+
+export declare interface HotConformanceFixture {
+    readonly layer: Layer.Layer<HotStore, unknown>;
+    readonly advance: (ms: number) => Effect.Effect<void>;
+    readonly capabilities: HotStoreShape['capabilities'];
+}
+
+declare interface HotCounterOptions extends HotTtl {
+    readonly max?: number;
+}
+
+/** Ephemeral data failures. SQL remains the durable source of truth. */
+declare class HotError extends HotError_base {
+}
+
+declare const HotError_base: Schema.Class<HotError, Schema.TaggedStruct<"HotError", {
+    readonly operation: Schema.String;
+    readonly key: Schema.String;
+    readonly reason: Schema.Literals<readonly ["invalid", "wrongType", "limit", "unavailable"]>;
+}>, YieldableError>;
+
+declare interface HotMember {
+    readonly member: string;
+    readonly score: number;
+}
+
+/** Operations accepted by an atomic batch. A batch cannot contain a scan. */
+declare type HotOp = {
+    readonly op: 'zadd';
+    readonly key: string;
+    readonly members: ReadonlyArray<HotMember>;
+    readonly options?: HotZaddOptions;
+} | {
+    readonly op: 'zrem';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+} | {
+    readonly op: 'zrank';
+    readonly key: string;
+    readonly member: string;
+    readonly order: HotOrder;
+} | {
+    readonly op: 'zscore';
+    readonly key: string;
+    readonly member: string;
+} | {
+    readonly op: 'zrange';
+    readonly key: string;
+    readonly range: HotRange;
+    readonly order: HotOrder;
+    readonly options?: Pick<HotRangeOptions, 'limit'>;
+} | {
+    readonly op: 'zcard';
+    readonly key: string;
+} | {
+    readonly op: 'zremRange';
+    readonly key: string;
+    readonly range: HotRange;
+} | {
+    readonly op: 'incrBy';
+    readonly key: string;
+    readonly delta: number;
+    readonly options?: HotCounterOptions;
+} | {
+    readonly op: 'tokenBucket';
+    readonly key: string;
+    readonly config: HotBucketConfig;
+    readonly cost: number;
+} | {
+    readonly op: 'rateLimit';
+    readonly key: string;
+    readonly config: HotRateLimitConfig;
+    readonly nowMs?: number;
+} | {
+    readonly op: 'hset';
+    readonly key: string;
+    readonly fields: Readonly<Record<string, string>>;
+    readonly options?: HotTtl;
+} | {
+    readonly op: 'hget';
+    readonly key: string;
+    readonly field: string;
+} | {
+    readonly op: 'hgetAll';
+    readonly key: string;
+} | {
+    readonly op: 'hdel';
+    readonly key: string;
+    readonly fields: ReadonlyArray<string>;
+} | {
+    readonly op: 'sadd';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+    readonly options?: HotTtl;
+} | {
+    readonly op: 'srem';
+    readonly key: string;
+    readonly members: ReadonlyArray<string>;
+} | {
+    readonly op: 'smembers';
+    readonly key: string;
+} | {
+    readonly op: 'sismember';
+    readonly key: string;
+    readonly member: string;
+} | {
+    readonly op: 'setNx';
+    readonly key: string;
+    readonly value: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'compareDelete';
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly op: 'compareExpire';
+    readonly key: string;
+    readonly value: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'expire';
+    readonly key: string;
+    readonly ttlMs: number;
+} | {
+    readonly op: 'delete';
+    readonly key: string;
+};
+
+declare type HotOrder = 'asc' | 'desc';
+
+declare type HotRange = {
+    readonly byRank: readonly [number, number];
+} | {
+    readonly byScore: readonly [number, number];
+};
+
+declare interface HotRangeOptions extends HotReadOptions {
+    readonly limit?: number;
+}
+
+declare interface HotRateLimitConfig {
+    readonly algorithm: 'fixed-window' | 'sliding-window' | 'token-bucket';
+    readonly limit: number;
+    readonly windowMs: number;
+    readonly burst: number;
+}
+
+declare interface HotRateLimitResult extends HotBucketResult {
+    readonly resetAtMs: number;
+}
+
+/** Default reads use the primary. Eventual reads may observe a replica. */
+declare interface HotReadOptions {
+    readonly consistency?: 'primary' | 'eventual';
+}
+
+declare class HotStore extends HotStore_base {
+}
+
+declare const HotStore_base: Context.ServiceClass<HotStore, "@voltro/HotStore", HotStoreShape>;
+
+/** Run exactly the same behavioral contract against a backend or a replacement port. */
+export declare const hotStoreConformance: (name: string, fixture: () => HotConformanceFixture) => void;
+
+declare interface HotStoreShape {
+    readonly zadd: (key: string, members: ReadonlyArray<HotMember>, options?: HotZaddOptions) => Effect.Effect<void, HotError>;
+    readonly zrem: (key: string, members: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly zrank: (key: string, member: string, order: HotOrder, options?: HotReadOptions) => Effect.Effect<Option.Option<number>, HotError>;
+    readonly zscore: (key: string, member: string, options?: HotReadOptions) => Effect.Effect<Option.Option<number>, HotError>;
+    readonly zrange: (key: string, range: HotRange, order: HotOrder, options?: HotRangeOptions) => Effect.Effect<ReadonlyArray<HotMember>, HotError>;
+    readonly zcard: (key: string, options?: HotReadOptions) => Effect.Effect<number, HotError>;
+    readonly zremRange: (key: string, range: HotRange) => Effect.Effect<number, HotError>;
+    readonly incrBy: (key: string, delta: number, options?: HotCounterOptions) => Effect.Effect<number, HotError>;
+    readonly tokenBucket: (key: string, config: HotBucketConfig, cost?: number) => Effect.Effect<HotBucketResult, HotError>;
+    /** Atomically check and consume one request. nowMs is trusted server/test time. */
+    readonly rateLimit: (key: string, config: HotRateLimitConfig, nowMs?: number) => Effect.Effect<HotRateLimitResult, HotError>;
+    readonly hset: (key: string, fields: Readonly<Record<string, string>>, options?: HotTtl) => Effect.Effect<void, HotError>;
+    readonly hget: (key: string, field: string, options?: HotReadOptions) => Effect.Effect<Option.Option<string>, HotError>;
+    readonly hgetAll: (key: string, options?: HotReadOptions) => Effect.Effect<Readonly<Record<string, string>>, HotError>;
+    readonly hdel: (key: string, fields: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly sadd: (key: string, members: ReadonlyArray<string>, options?: HotTtl) => Effect.Effect<number, HotError>;
+    readonly srem: (key: string, members: ReadonlyArray<string>) => Effect.Effect<number, HotError>;
+    readonly smembers: (key: string, options?: HotReadOptions) => Effect.Effect<ReadonlyArray<string>, HotError>;
+    readonly sismember: (key: string, member: string, options?: HotReadOptions) => Effect.Effect<boolean, HotError>;
+    readonly setNx: (key: string, value: string, ttlMs: number) => Effect.Effect<boolean, HotError>;
+    /** Atomically delete a setNx lease only while its value matches. Missing/mismatch returns false. */
+    readonly compareDelete: (key: string, value: string) => Effect.Effect<boolean, HotError>;
+    /** Atomically reset a matching setNx lease's TTL. Other structures fail with wrongType. */
+    readonly compareExpire: (key: string, value: string, ttlMs: number) => Effect.Effect<boolean, HotError>;
+    readonly expire: (key: string, ttlMs: number) => Effect.Effect<void, HotError>;
+    readonly delete: (key: string) => Effect.Effect<boolean, HotError>;
+    readonly scanPrefix: (prefix: string) => Stream.Stream<string, HotError>;
+    /** Isolated batch. Arguments are validated first. Like Redis MULTI, a backend
+     * need not roll back commands preceding a server-side execution failure. */
+    readonly multi: (operations: ReadonlyArray<HotOp>) => Effect.Effect<ReadonlyArray<unknown>, HotError>;
+    readonly capabilities: {
+        readonly atomicMulti: boolean;
+        readonly crossNode: boolean;
+        readonly persistent: boolean;
+    };
+}
+
+declare interface HotTtl {
+    readonly ttlMs?: number;
+}
+
+declare interface HotZaddOptions extends HotTtl {
+    readonly mode?: 'set' | 'max' | 'min' | 'incr';
+}
+
+export { }

package/dist/hot-testing.js

@@ -0,0 +1 @@
+export { hotStoreConformance } from "./hotStoreConformance.js";