@voltro/kv 0.86.0 → 0.88.0

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,47 @@
+import { StorageAddress as e, isStorageKey as t, storageAddressIdentity as n, storageKeyProblem as r } from "./storageAddress.js";
+import { Schema as i } from "effect";
+// 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);
+};
+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,19 @@
+import { Schema as e } from "effect";
+// 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
+]);
+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.86.0",
+  "version": "0.88.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,25 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "optionalDependencies": {
-    "@upstash/redis": "^1.38.4",
-    "ioredis": "^5.11.1"
+  "dependencies": {
+    "@voltro/shared": "0.88.0"
   },
   "peerDependencies": {
-    "effect": "4.0.1"
+    "effect": "4.1.0",
+    "@nats-io/transport-node": "^3.4.0",
+    "@upstash/redis": "^1.40.0",
+    "ioredis": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nats-io/transport-node": {
+      "optional": true
+    },
+    "@upstash/redis": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"