@voltro/kv 0.85.0 → 0.87.0

package/dist/sql.d.ts

@@ -0,0 +1,77 @@
+import { Config } from 'effect';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { Stream } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+declare interface ConnectionContext {
+    readonly tenantId: string;
+}
+
+/** An environment declaration, never the environment value itself. */
+declare interface ConnectionEnv {
+    readonly _tag: 'ConnectionEnv';
+    readonly name: string;
+}
+
+export declare interface DynamicSqlConnection {
+    readonly _tag: 'DynamicSqlConnection';
+    readonly resolve: (context: ConnectionContext) => Effect.Effect<SqlConnectionConfig, KvError>;
+    readonly ttlMs: number;
+}
+
+declare class KvError extends KvError_base {
+    get message(): string;
+}
+
+declare const KvError_base: Schema.Class<KvError, Schema.TaggedStruct<"KvError", {
+    /** Which op failed: 'get' | 'set' | 'delete' | 'has' | 'clear' |
+     *  'list' | 'connect' | 'serialize' | 'deserialize'. */
+    readonly operation: Schema.String;
+    /** The key (or connection name) involved; '' where not applicable. */
+    readonly key: Schema.String;
+    /** `String(originalError)` — round-trip-safe diagnostic form. */
+    readonly cause: Schema.String;
+}>, YieldableError>;
+
+/** A whole operation (including its transaction) borrows one physical generation.
+ * Do not return the client, a deferred statement or a stream from use: execute it
+ * inside the callback. Use stream for a lazy result that must retain its lease. */
+export declare interface SqlConnection {
+    readonly dialect: SqlConnectionConfig['dialect'];
+    readonly use: <A, E, R>(run: (client: SqlClient.SqlClient) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | KvError | Config.ConfigError, R>;
+    readonly stream: <A, E, R>(run: (client: SqlClient.SqlClient) => Stream.Stream<A, E, R>) => Stream.Stream<A, E | KvError | Config.ConfigError, R>;
+}
+
+/** Additional SQL target. The primary DataStore retains its own configuration. */
+export declare interface SqlConnectionConfig {
+    readonly dialect: SqlConnectionDialect;
+    readonly url: string;
+    readonly tls?: 'auto' | 'required';
+    readonly maxConnections?: number;
+    readonly acquireTimeoutMs?: number;
+    readonly acquireQueueLimit?: number;
+    readonly statementTimeoutMs?: number;
+    readonly schema?: string;
+    readonly label?: string;
+    readonly region?: string;
+    readonly source?: 'config' | 'override';
+}
+
+export declare type SqlConnectionConnector = (config: SqlConnectionConfig) => Effect.Effect<SqlConnectionTransport, KvError>;
+
+export declare interface SqlConnectionDefinition extends Omit<SqlConnectionConfig, 'url' | 'source'> {
+    readonly url: ConnectionEnv;
+}
+
+export declare type SqlConnectionDialect = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
+
+/** Connector-owned resources; a consumer never receives physical disposal. */
+export declare interface SqlConnectionTransport {
+    readonly client: SqlClient.SqlClient;
+    readonly probe: Effect.Effect<void, KvError>;
+    readonly close: Effect.Effect<void>;
+}
+
+export { }

package/dist/storage.d.ts

@@ -0,0 +1,166 @@
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { Stream } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+export declare type ByteStream = Stream.Stream<Uint8Array, StorageError>;
+
+declare interface ConnectionMetadata {
+    readonly tls?: 'auto' | 'required';
+    readonly persistence?: 'required' | 'optional' | 'none';
+    readonly keyPrefix?: string;
+    /** Explicit opt-in when a production connection intentionally uses a shared namespace. */
+    readonly allowSharedNamespace?: boolean;
+    readonly region?: string;
+    readonly label?: string;
+    readonly acl?: string;
+}
+
+/** Stable consumer identity while boot replaces its transport with a borrowed port. */
+export declare const forwardStorageProvider: (current: () => StorageProvider) => StorageProvider;
+
+export declare const isStorageKey: (value: string) => boolean;
+
+export declare interface ObjectMeta {
+    readonly size: number;
+    readonly etag?: string;
+    /** Read-only metadata for lazy, leased streaming reads. */
+    readonly contentType?: string;
+}
+
+/** A logical destination label, tenant and provider key identify one object. */
+export declare const StorageAddress: Schema.Struct<{
+    readonly destination: Schema.String;
+    readonly tenantId: Schema.NullOr<Schema.String>;
+    readonly key: Schema.String;
+}>;
+
+export declare type StorageAddress = Schema.Schema.Type<typeof StorageAddress>;
+
+/** Tuple encoding cannot alias delimiter-bearing labels, tenants or keys. */
+export declare const storageAddressIdentity: (address: StorageAddress) => string;
+
+/** Resolved values stay server-side and never enter inspection snapshots. */
+export declare interface StorageConnectionConfig extends ConnectionMetadata {
+    readonly provider: StorageProviderName;
+    readonly bucket?: string;
+    readonly root?: string;
+    readonly endpoint?: string;
+    readonly accessKeyId?: string;
+    readonly secretAccessKey?: string;
+    readonly accountName?: string;
+    readonly accountKey?: string;
+    readonly connectionString?: string;
+    readonly cdnBaseUrl?: string;
+    readonly forcePathStyle?: boolean;
+    readonly publicAcl?: boolean;
+    readonly source?: 'config' | 'environment' | 'override';
+}
+
+export declare type StorageConnectionConnector = (config: StorageConnectionConfig, context: StorageConnectionOpenContext) => Effect.Effect<StorageConnectionTransport, StorageError>;
+
+export declare interface StorageConnectionOpenContext {
+    /** Local state belongs to this registry identity, preserved across physical rotation. */
+    readonly memory?: Map<string, StoredObject>;
+}
+
+/** A transport is created lazily; only the registry owns its physical disposal. */
+export declare interface StorageConnectionTransport {
+    readonly provider: StorageProvider;
+    readonly probe: Effect.Effect<void, StorageError>;
+    readonly close: Effect.Effect<void>;
+}
+
+export declare interface StorageDestination {
+    readonly destination: string;
+    /** Borrowed transport; its registry owns connections and operation leases. */
+    readonly provider: StorageProvider;
+}
+
+/** Select new writes separately from resolving immutable SQL ownership. */
+export declare interface StorageDestinationRouter {
+    readonly select: (tenantId: string | null) => Effect.Effect<StorageDestination, StorageError>;
+    readonly resolve: (address: StorageAddress) => Effect.Effect<StorageProvider, StorageError>;
+}
+
+/** The object transport error, shared with the storage plugin's wire contract. */
+export declare class StorageError extends StorageError_base {
+}
+
+declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
+    readonly provider: Schema.String;
+    readonly message: Schema.String;
+    readonly transient: Schema.Boolean;
+    readonly status: Schema.optional<Schema.Number>;
+    /** Cleanup was not confirmed; inspect the destination before another write. */
+    readonly outcome: Schema.optional<Schema.Literal<"unknown">>;
+}>, YieldableError>;
+
+/** Logical object keys never contain filesystem traversal or empty segments. */
+export declare const storageKeyProblem: (value: string) => string | undefined;
+
+/** Server-side physical identity; never serialize a namespace into inspection. */
+export declare interface StorageObjectLocation {
+    readonly namespace: string | object;
+    readonly key: string;
+}
+
+/** Opaque keyed bytes; policy and durable references belong to the plugin. */
+export declare interface StorageProvider {
+    /** Stable, credential-independent SHA-256 identity of this physical key namespace. */
+    readonly objectNamespace: Effect.Effect<string, StorageError>;
+    /** Canonical container and physical key, including connection prefixes. */
+    readonly objectLocation?: (key: string) => Effect.Effect<StorageObjectLocation, StorageError>;
+    readonly root?: string;
+    readonly name: string;
+    readonly presigns: boolean;
+    readonly put: (key: string, bytes: Uint8Array, meta: {
+        readonly contentType: string;
+        readonly public?: boolean;
+    }) => Effect.Effect<ObjectMeta, StorageError>;
+    readonly get: (key: string) => Effect.Effect<StoredObject, StorageError>;
+    readonly delete: (key: string) => Effect.Effect<void, StorageError>;
+    readonly getUrl: (key: string, expiresInSec: number) => Effect.Effect<string, StorageError>;
+    readonly publicUrl?: (key: string) => string | null;
+    readonly setObjectPublic?: (key: string, isPublic: boolean) => Effect.Effect<void, StorageError>;
+    readonly getUploadUrl?: (key: string, expiresInSec: number, contentType: string) => Effect.Effect<string, StorageError>;
+    readonly createMultipartUpload?: (key: string, contentType: string, opts?: {
+        readonly public?: boolean;
+    }) => Effect.Effect<{
+        readonly uploadId: string;
+    }, StorageError>;
+    readonly presignUploadPart?: (key: string, uploadId: string, partNumber: number, expiresInSec: number) => Effect.Effect<string, StorageError>;
+    readonly completeMultipartUpload?: (key: string, uploadId: string, parts: ReadonlyArray<{
+        readonly partNumber: number;
+        readonly etag: string;
+    }>) => Effect.Effect<{
+        readonly etag?: string;
+    }, StorageError>;
+    readonly abortMultipartUpload?: (key: string, uploadId: string) => Effect.Effect<void, StorageError>;
+    readonly head: (key: string) => Effect.Effect<ObjectMeta | null, StorageError>;
+    readonly getStream?: (key: string) => Effect.Effect<StoredStream, StorageError>;
+    readonly putStream?: (key: string, stream: ByteStream, meta: {
+        readonly contentType: string;
+        readonly public?: boolean;
+        readonly totalSize?: number;
+    }) => Effect.Effect<ObjectMeta, StorageError>;
+    readonly getRange?: (key: string, start: number, endInclusive: number) => Effect.Effect<Uint8Array, StorageError>;
+    readonly bindDataStore?: (store: unknown) => void;
+}
+
+export declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
+
+export declare interface StoredObject {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}
+
+export declare interface StoredStream {
+    readonly stream: ByteStream;
+    readonly contentType: string;
+    readonly size?: number;
+    /** Release an opened body even if cancellation precedes its first pull. */
+    readonly close?: Effect.Effect<void>;
+}
+
+export { }

package/dist/storage.js

@@ -0,0 +1,48 @@
+import { StorageAddress as e, isStorageKey as t, storageAddressIdentity as n, storageKeyProblem as r } from "./storageAddress.js";
+import { Schema as i } from "effect";
+//#region src/connectionStorage.ts
+var a = class extends i.TaggedError()("StorageError", {
+	provider: i.String,
+	message: i.String,
+	transient: i.Boolean,
+	status: i.optional(i.Number),
+	outcome: i.optional(i.Literal("unknown"))
+}) {}, o = (e) => {
+	let t = {
+		get objectNamespace() {
+			return e().objectNamespace;
+		},
+		get name() {
+			return e().name;
+		},
+		get presigns() {
+			return e().presigns;
+		},
+		put: (...t) => e().put(...t),
+		get: (...t) => e().get(...t),
+		delete: (...t) => e().delete(...t),
+		getUrl: (...t) => e().getUrl(...t),
+		head: (...t) => e().head(...t)
+	}, n = {};
+	for (let t of [
+		"objectLocation",
+		"root",
+		"publicUrl",
+		"setObjectPublic",
+		"getUploadUrl",
+		"createMultipartUpload",
+		"presignUploadPart",
+		"completeMultipartUpload",
+		"abortMultipartUpload",
+		"getStream",
+		"putStream",
+		"getRange",
+		"bindDataStore"
+	]) n[t] = {
+		enumerable: !0,
+		get: () => e()[t]
+	};
+	return Object.defineProperties(t, n);
+};
+//#endregion
+export { e as StorageAddress, a as StorageError, o as forwardStorageProvider, t as isStorageKey, n as storageAddressIdentity, r as storageKeyProblem };

package/dist/storageAddress.js

@@ -0,0 +1,20 @@
+import { Schema as e } from "effect";
+//#region src/storageAddress.ts
+var t = (e) => {
+	if (e.length === 0) return "empty";
+	if (e.includes("\0")) return "contains NUL";
+	if (e.includes("\\")) return "contains a backslash";
+	if (e.startsWith("/") || /^[a-z]:/i.test(e)) return "starts with a path separator";
+	if (/[\uD800-\uDFFF]/u.test(e)) return "contains an unpaired surrogate";
+	if (e.split("/").some((e) => e === "" || e === "." || e === "..")) return "contains an empty, \".\" or \"..\" segment";
+}, n = (e) => t(e) === void 0, r = e.Struct({
+	destination: e.String.pipe(e.check(e.isMinLength(1)), e.check(e.isMaxLength(512)), e.check(e.makeFilter((e) => !e.includes("\0") && !/[\uD800-\uDFFF]/u.test(e)))),
+	tenantId: e.NullOr(e.String.pipe(e.check(e.isMinLength(1)), e.check(e.makeFilter((e) => !e.includes("\0") && !/[\uD800-\uDFFF]/u.test(e))))),
+	key: e.String.pipe(e.check(e.makeFilter(n)))
+}), i = (e) => JSON.stringify([
+	e.destination,
+	e.tenantId,
+	e.key
+]);
+//#endregion
+export { r as StorageAddress, n as isStorageKey, i as storageAddressIdentity, t as storageKeyProblem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/kv",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "Named RESP connection registry + durable key-value primitive. One config surface for many Redis-family connections (Redis/Valkey/KeyDB/Dragonfly/Upstash) shared across cache, rate-limit, RYW and broadcast; plus a durable, tenant-scoped KV store distinct from the best-effort cache.",
   "keywords": [
     "voltro",
@@ -28,7 +28,37 @@
       "import": "./dist/connection.js",
       "default": "./dist/connection.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./hot": {
+      "types": "./dist/hot.d.ts",
+      "import": "./dist/hot.js",
+      "default": "./dist/hot.js"
+    },
+    "./hot/testing": {
+      "types": "./dist/hot-testing.d.ts",
+      "import": "./dist/hot-testing.js",
+      "default": "./dist/hot-testing.js"
+    },
+    "./hot/contract": {
+      "types": "./dist/hot-contract.d.ts",
+      "import": "./dist/hot-contract.js",
+      "default": "./dist/hot-contract.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics.d.ts",
+      "import": "./dist/analytics.js",
+      "default": "./dist/analytics.js"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.ts",
+      "import": "./dist/sql.js",
+      "default": "./dist/sql.js"
+    }
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -37,12 +67,22 @@
   "engines": {
     "node": ">=24.0.0"
   },
+  "dependencies": {
+    "@voltro/shared": "0.87.0"
+  },
   "optionalDependencies": {
+    "@nats-io/transport-node": "^3.4.0",
     "@upstash/redis": "^1.38.4",
     "ioredis": "^5.11.1"
   },
   "peerDependencies": {
-    "effect": "4.0.1"
+    "effect": "4.0.1",
+    "vitest": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"

package/dist/connection-Dsn5fgcH.js

@@ -1,84 +0,0 @@
-import { Config as e, Context as t, Effect as n, HashMap as r, Layer as i, Option as a, Schedule as o, Schema as s, Scope as c, SynchronizedRef as l } from "effect";
-//#region src/errors.ts
-var u = class extends s.TaggedError()("KvError", {
-	operation: s.String,
-	key: s.String,
-	cause: s.String
-}) {}, d = (e) => ({
-	get: (t) => e.get(t),
-	set: (t, n) => e.set(t, n),
-	psetex: (t, n, r) => e.psetex(t, n, r),
-	del: (t) => t.length === 0 ? Promise.resolve(0) : e.del(...t),
-	exists: (t) => e.exists(t),
-	eval: (t, n, ...r) => e.eval(t, n, ...r),
-	zrange: (t) => e.zrange(t, 0, -1),
-	scan: async (t, n, r) => {
-		let [i, a] = await e.scan(t, "MATCH", n, "COUNT", r);
-		return {
-			cursor: i,
-			keys: a
-		};
-	},
-	close: () => e.quit().then(() => void 0).catch(() => {
-		try {
-			e.disconnect();
-		} catch {}
-	})
-}), f = (e) => ({
-	get: (t) => e.get(t),
-	set: (t, n) => e.set(t, n),
-	psetex: (t, n, r) => e.psetex(t, n, r),
-	del: (t) => t.length === 0 ? Promise.resolve(0) : e.del(...t),
-	exists: (t) => e.exists(t),
-	eval: (t, n, ...r) => e.eval(t, r.slice(0, n), r.slice(n)),
-	zrange: (t) => e.zrange(t, 0, -1),
-	scan: async (t, n, r) => {
-		let [i, a] = await e.scan(t, {
-			match: n,
-			count: r
-		});
-		return {
-			cursor: String(i),
-			keys: a
-		};
-	},
-	close: () => Promise.resolve()
-}), p = (e) => e.toUpperCase().replace(/[^A-Z0-9]+/g, "_"), m = ["resp", "http"], h = (t) => n.gen(function* () {
-	let n = p(t), r = yield* e.String(`${n}_REDIS_URL`).pipe(e.orElse(() => e.String("REDIS_URL"))), i = yield* e.Literals(m, `${n}_REDIS_DRIVER`).pipe(e.option), o = a.isSome(i) ? i.value : yield* e.Literals(m, "REDIS_DRIVER").pipe(e.withDefault("resp")), s = yield* e.String(`${n}_REDIS_TOKEN`).pipe(e.orElse(() => e.String("REDIS_TOKEN")), e.orElse(() => e.String("UPSTASH_REDIS_REST_TOKEN")), e.option), c = yield* e.String(`${n}_REDIS_KEY_PREFIX`).pipe(e.option);
-	return {
-		url: r,
-		driver: o,
-		...a.isSome(s) ? { token: s.value } : {},
-		...a.isSome(c) ? { keyPrefix: c.value } : {}
-	};
-}), g = (e) => n.tryPromise({
-	try: async () => {
-		if (e.driver === "http") {
-			let t = await import("@upstash/redis"), n = typeof t.default == "function" ? t.default : t.default?.Redis, r = t.Redis ?? n;
-			if (!r) throw Error("@upstash/redis: Redis constructor not found in module");
-			return f(new r({
-				url: e.url,
-				token: e.token,
-				automaticDeserialization: !1
-			}));
-		}
-		let t = (await import("ioredis")).default, n = new t(e.url);
-		return n.on("error", () => {}), d(n);
-	},
-	catch: (e) => new u({
-		operation: "connect",
-		key: "",
-		cause: String(e)
-	})
-}), _ = o.max([o.exponential("10 millis"), o.recurs(2)]), v = class extends t.Service()("@voltro/RedisConnections") {}, y = i.effect(v, n.gen(function* () {
-	let e = yield* n.scope, t = yield* l.make(r.empty()), i = (e) => h(e);
-	return {
-		client: (o) => l.modifyEffect(t, (t) => {
-			let s = r.get(t, o);
-			return a.isSome(s) ? n.succeed([s.value, t]) : i(o).pipe(n.flatMap(g), n.tap((t) => c.addFinalizer(e, n.promise(() => t.close().catch(() => void 0)))), n.map((e) => [e, r.set(t, o, e)]));
-		}),
-		config: i
-	};
-}));
-//#endregion
-export { y as a, h as i, _ as n, u as o, g as r, v as t };