@nice-code/util 0.6.3 → 0.8.0

package/build/index.js

@@ -918,11 +918,13 @@ class StorageAdapter {
     const currentVal = await this.getJson(rawKey);
     const newVal = updater(currentVal);
     await this.setJson(rawKey, newVal);
+    return newVal;
   }
   async updateJsonOrDef(rawKey, defVal, updater) {
     const currentVal = await this.getJsonOrDef(rawKey, defVal);
     const newVal = updater(currentVal);
     await this.setJson(rawKey, newVal);
+    return newVal;
   }
   createJsonGetterSetter(rawKey) {
     return {
@@ -984,7 +986,7 @@ function createTypedWebSessionStorage(options) {
     storageAdapter: createWebSessionStorageAdapter(options)
   });
 }
-// src/storage_adapter/specific/durable_object/durable_object_storage.ts
+// src/storage_adapter/specific/cloudflare/durable_object/durable_object_storage.ts
 function createDurableObjectStorageMethods(durableObjectStorage) {
   return {
     type: "json" /* json */,
@@ -1009,6 +1011,33 @@ function createDurableObjectTypedStorage(options) {
     storageAdapter: createDurableObjectStorageAdapter(options)
   });
 }
+// src/storage_adapter/specific/cloudflare/kv/kv_storage.ts
+function createKVStorageMethods({
+  kvNamespace,
+  defaultPutOptions
+}) {
+  return {
+    type: "string" /* string */,
+    getItem: (key) => kvNamespace.get(key),
+    setItem: (key, value) => kvNamespace.put(key, value, defaultPutOptions),
+    removeItem: (key) => kvNamespace.delete(key)
+  };
+}
+var createKVStorageAdapter = ({
+  kvNamespace,
+  defaultPutOptions,
+  ...options
+}) => {
+  return new StorageAdapter({
+    methods: createKVStorageMethods({ kvNamespace, defaultPutOptions }),
+    ...options
+  });
+};
+function createKVTypedStorage(options) {
+  return createTypedStorage({
+    storageAdapter: createKVStorageAdapter(options)
+  });
+}
 // src/storage_adapter/specific/memory/memory_storage.ts
 function createMemoryStorageMethods_string(memoryStorageMap = new Map) {
   return {
@@ -1095,6 +1124,9 @@ export {
   createMemoryStorageMethods_json,
   createMemoryStorageAdapter_string,
   createMemoryStorageAdapter_json,
+  createKVTypedStorage,
+  createKVStorageMethods,
+  createKVStorageAdapter,
   createDurableObjectTypedStorage,
   createDurableObjectStorageMethods,
   createDurableObjectStorageAdapter,

package/build/types/index.d.ts

@@ -2,7 +2,8 @@ export type { TTypeAndId } from "./core/core_valibot_schemas";
 export * from "./crypto";
 export * from "./storage_adapter/StorageAdapter";
 export * from "./storage_adapter/specific/browser/browser_storage";
-export * from "./storage_adapter/specific/durable_object/durable_object_storage";
+export * from "./storage_adapter/specific/cloudflare/durable_object/durable_object_storage";
+export * from "./storage_adapter/specific/cloudflare/kv/kv_storage";
 export * from "./storage_adapter/specific/memory/memory_storage";
 export * from "./storage_adapter/storage_adapter.types";
 export * from "./storage_adapter/typed_storage/createTypedStorage";

package/build/types/storage_adapter/StorageAdapter.d.ts

@@ -17,7 +17,7 @@ export declare class StorageAdapter {
     setJson(rawKey: string, value: any): Promise<void>;
     getJson<T>(rawKey: string): Promise<T | undefined>;
     getJsonOrDef<T>(rawKey: string, defVal: T): Promise<T>;
-    updateJson<T>(rawKey: string, updater: (currentVal: T | undefined) => T): Promise<void>;
-    updateJsonOrDef<T>(rawKey: string, defVal: T, updater: (currentVal: T) => T): Promise<void>;
+    updateJson<T>(rawKey: string, updater: (currentVal: T | undefined) => T): Promise<T>;
+    updateJsonOrDef<T>(rawKey: string, defVal: T, updater: (currentVal: T) => T): Promise<T>;
     createJsonGetterSetter<T>(rawKey: string): IStorageKeyGetterAndSetter<T>;
 }

package/build/types/storage_adapter/specific/{durable_object → cloudflare/durable_object}/durable_object_storage.d.ts

@@ -1,6 +1,6 @@
-import { type IStorageAdapterConstructor, StorageAdapter } from "../../StorageAdapter";
-import { type IStorageAdapterMethods_Json } from "../../storage_adapter.types";
-import { type ITypedStorage } from "../../typed_storage/createTypedStorage";
+import { type IStorageAdapterConstructor, StorageAdapter } from "../../../StorageAdapter";
+import { type IStorageAdapterMethods_Json } from "../../../storage_adapter.types";
+import { type ITypedStorage } from "../../../typed_storage/createTypedStorage";
 import type { IDurableObjectStorage } from "./durable_object_storage.types";
 export declare function createDurableObjectStorageMethods(durableObjectStorage: IDurableObjectStorage): IStorageAdapterMethods_Json;
 export type TCreateDurableObjectStorageOptions = Omit<IStorageAdapterConstructor, "methods"> & {

package/build/types/storage_adapter/specific/cloudflare/kv/kv_storage.d.ts

@@ -0,0 +1,18 @@
+import { type IStorageAdapterConstructor, StorageAdapter } from "../../../StorageAdapter";
+import { type IStorageAdapterMethods_String } from "../../../storage_adapter.types";
+import { type ITypedStorage } from "../../../typed_storage/createTypedStorage";
+import type { IKVNamespace, IKVNamespacePutOptions } from "./kv_storage.types";
+export interface ICreateKVStorageMethodsOptions {
+    /** The `KVNamespace` binding, e.g. accessed off `env.MY_KV` inside a worker. */
+    kvNamespace: IKVNamespace;
+    /** Default options applied to every `put`, e.g. `{ expirationTtl }` for TTL-based eviction. */
+    defaultPutOptions?: IKVNamespacePutOptions;
+}
+export declare function createKVStorageMethods({ kvNamespace, defaultPutOptions, }: ICreateKVStorageMethodsOptions): IStorageAdapterMethods_String;
+export type TCreateKVStorageOptions = Omit<IStorageAdapterConstructor, "methods"> & ICreateKVStorageMethodsOptions;
+/**
+ * Wraps a Cloudflare KV namespace binding in the generic StorageAdapter interface, e.g. for handing
+ * to a ClientCryptoKeyLink so it can persist its keys inside KV.
+ */
+export declare const createKVStorageAdapter: ({ kvNamespace, defaultPutOptions, ...options }: TCreateKVStorageOptions) => StorageAdapter;
+export declare function createKVTypedStorage<T extends Record<string, any>>(options: TCreateKVStorageOptions): ITypedStorage<T>;

package/build/types/storage_adapter/specific/cloudflare/kv/kv_storage.types.d.ts

@@ -0,0 +1,22 @@
+interface IKVNamespaceGetOptions {
+    cacheTtl?: number;
+}
+interface IKVNamespacePutOptions {
+    /** Absolute time (seconds since epoch) at which the key should expire. */
+    expiration?: number;
+    /** Relative TTL (in seconds) from now, after which the key should expire. */
+    expirationTtl?: number;
+    metadata?: unknown;
+}
+/**
+ * Minimal subset of Cloudflare's `KVNamespace` binding that our storage adapter relies on. Values
+ * are always written/read as strings (KV's `put` only accepts string/stream/buffer values), so the
+ * adapter is a {@link EStorageAdapterType.string} adapter and JSON (de)serialization happens in the
+ * generic `StorageAdapter`.
+ */
+export interface IKVNamespace {
+    get(key: string, options?: IKVNamespaceGetOptions): Promise<string | null>;
+    put(key: string, value: string, options?: IKVNamespacePutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export type { IKVNamespaceGetOptions, IKVNamespacePutOptions };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@nice-code/util",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "exports": {
     ".": {
-      "types": "./build/types/index.d.ts",
-      "import": "./build/index.js"
+      "source": "./src/index.ts",
+      "import": "./build/index.js",
+      "types": "./build/types/index.d.ts"
     }
   },
   "files": [
@@ -30,7 +31,9 @@
   "dependencies": {
     "nanoid": "^5.1.9"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "@scure/base": "^2.2.0"
+  },
   "peerDependencies": {
     "@tanstack/react-query": "^5.100.3",
     "react": ">=19",