feat: importing and exporting utilities (#6)

Provides the ability to import and export Deno KV entries as new-line
delimitated JSON in various forms.

Closes #2

.gitignore

@@ -0,0 +1 @@
+export.ndjson

README.md

@@ -81,6 +81,65 @@ const value = { a: new Map([[{ a: 1 }, { b: /234/ }]]), b: false };
 assertEquals(estimateSize(value), 36);
 ```
 
+## Importing and exporting entries
+
+Deno KV stores can be exported and imported. This is useful for backing up and
+restoring data, as well as for transferring data between different Deno
+processes.
+
+The import and export utilities are:
+
+- `exportEntries` - Export entries from a Deno KV store as a stream or a
+  response.
+- `importEntries` - Import entries into a Deno KV store.
+
+### Examples
+
+Exporting entries from a Deno KV store and saving them to a file:
+
+```ts
+import { exportEntries } from "@deno/kv-utils";
+
+const db = await Deno.openKv();
+const file = await Deno.open("export.ndjson", { write: true, create: true });
+for await (const chunk of exportEntries(db, { prefix: ["person"] })) {
+  await file.write(chunk);
+}
+file.close();
+db.close();
+```
+
+Exporting entries from a Deno KV store and sending them as a response:
+
+```ts ignore
+import { exportEntries } from "@deno/kv-utils";
+
+const db = await Deno.openKv();
+const server = Deno.serve((_req) =>
+  exportEntries(
+    db,
+    { prefix: ["person"] },
+    { type: "response" },
+  )
+);
+
+await server.finished;
+db.close();
+```
+
+Importing entries from a file and storing them in a Deno KV store:
+
+```ts
+import { importEntries } from "@deno/kv-utils";
+import { assert } from "@std/assert";
+
+const db = await Deno.openKv();
+const file = await Deno.open("export.ndjson", { read: true });
+const result = await importEntries(db, file.readable);
+assert(result.errors === 0);
+db.close();
+```
+
 # License
 
 MIT

_test_util.ts

@@ -0,0 +1,27 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+import { assert } from "@std/assert";
+
+let kv: { close(): void } | undefined;
+let path: string | undefined;
+
+/**
+ * Creates a temporary `Deno.Kv` instance and returns it.
+ *
+ * @returns the temporary `Deno.Kv` instance
+ */
+export async function setup() {
+  return kv = await Deno.openKv(path = `${await Deno.makeTempDir()}/test.db`);
+}
+
+/**
+ * Closes the temporary `Deno.Kv` instance and removes the temporary store.
+ *
+ * @returns the promise which resolves when the temporary store is removed
+ */
+export function teardown() {
+  assert(kv);
+  kv.close();
+  assert(path);
+  return Deno.remove(path);
+}

deno.json

@@ -3,20 +3,22 @@
   "version": "0.0.0",
   "exports": {
     ".": "./mod.ts",
-    "./json": "./json.ts",
-    "./estimate-size": "./estimate_size.ts"
+    "./estimate-size": "./estimate_size.ts",
+    "./import-export": "./import_export.ts",
+    "./json": "./json.ts"
   },
   "publish": {
-    "exclude": [".github", "_benches", "*_test.ts"]
+    "exclude": [".github", "_benches", "*.test.ts", "_test_util.ts"]
   },
   "imports": {
     "@std/assert": "jsr:@std/assert@^1.0.6",
+    "@std/bytes": "jsr:@std/bytes@^1.0.3",
     "@std/crypto": "jsr:@std/crypto@^1.0.3",
     "@std/encoding": "jsr:@std/encoding@^1.0.5"
   },
   "tasks": {
     "bench": "deno bench _benches/*.ts",
-    "test": "deno test --allow-net --unstable-kv --doc"
+    "test": "deno test --allow-net --allow-write --allow-read --unstable-kv --doc"
   },
   "lint": {
     "rules": {