{"id":18608498,"url":"https://github.com/denoland/kv-utils","last_synced_at":"2025-04-10T22:30:49.214Z","repository":{"id":261185738,"uuid":"883525402","full_name":"denoland/kv-utils","owner":"denoland","description":"The utilities for working with Deno KV","archived":false,"fork":false,"pushed_at":"2024-12-02T06:37:26.000Z","size":36,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-25T05:41:28.768Z","etag":null,"topics":["deno","denokv"],"latest_commit_sha":null,"homepage":"https://jsr.io/@deno/kv-utils","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denoland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-05T05:46:05.000Z","updated_at":"2025-03-02T15:36:37.000Z","dependencies_parsed_at":"2024-11-05T07:17:58.493Z","dependency_job_id":"1f7ebea0-ccc2-410f-a97e-9f0bd894a114","html_url":"https://github.com/denoland/kv-utils","commit_stats":{"total_commits":6,"total_committers":2,"mean_commits":3.0,"dds":"0.16666666666666663","last_synced_commit":"3266c17b6ffcdab56952f9bc7d310a3fe45e9646"},"previous_names":["denoland/kv-utils"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fkv-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fkv-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fkv-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoland%2Fkv-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denoland","download_url":"https://codeload.github.com/denoland/kv-utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248309336,"owners_count":21082195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","denokv"],"created_at":"2024-11-07T03:03:11.357Z","updated_at":"2025-04-10T22:30:49.203Z","avatar_url":"https://github.com/denoland.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @deno/kv-utils\n\nUtilities for working with Deno KV.\n\n## Working with JSON\n\n`Deno.Kv` stores are able to store values that are serializable using the\nstructured clone algorithm. The challenge is that supports a lot of types that\nare not serializable using JSON. To work around this, you can use the the\nutilities to convert values which can be safely serialized to JSON as well as\ndeserialize them back. This makes it possible to fully represent entries and\nvalues in a browser, or communicate them between Deno processes.\n\nThe JSON utilities are:\n\n- `entryMaybeToJSON` - Convert a `Deno.KvEntryMaybe` to JSON.\n- `entryToJSON` - Convert a `Deno.KvEntry` to JSON.\n- `keyToJSON` - Convert a `Deno.KvKey` to JSON.\n- `keyPartToJSON` - Convert a `Deno.KvKeyPart` to JSON.\n- `valueToJSON` - Convert a value which can be stored in Deno KV to JSON.\n- `toEntry` - Convert a JSON object to a `Deno.KvEntry`.\n- `toEntryMaybe` - Convert a JSON object to a `Deno.KvEntryMaybe`.\n- `toKey` - Convert a JSON object to a `Deno.KvKey`.\n- `toKeyPart` - Convert a JSON object to a `Deno.KvKeyPart`.\n- `toValue` - Convert a JSON object to a value which can be stored in Deno KV.\n\n### Examples\n\nTaking a maybe entry from Deno.Kv and converting it to JSON and sending it as a\nresponse:\n\n```ts ignore\nimport { entryMaybeToJSON } from \"@deno/kv-utils\";\n\nconst db = await Deno.openKv();\n\nDeno.serve(async (_req) =\u003e {\n  const maybeEntry = await db.get([\"a\"]);\n  const json = entryMaybeToJSON(maybeEntry);\n  return Response.json(json);\n});\n```\n\nTaking a value that was serialized to JSON in a browser and storing it in Deno\nKV:\n\n```ts ignore\nimport { toValue } from \"@deno/kv-utils\";\n\nconst db = await Deno.openKv();\n\nDeno.serve(async (req) =\u003e {\n  const json = await req.json();\n  const value = toValue(json);\n  await db.set([\"a\"], value);\n  return new Response(null, { status: 204 });\n});\n```\n\n## Estimating the size of a value\n\nWhen working with Deno KV and there is a need to have transactions be\ninfallible, it is helpful to be able to estimate the size of a value before\nstoring it. This is because there are limits on the size of values that can be\nstored in Deno KV, as well as the size of atomic operations.\n\nDeno KV stores values by using the V8 serialization format, which converts\nobjects to a binary format and then that value is stored in the KV store.\n\nThe `estimateSize` function can be used to estimate the size of a value in\nbytes. While it is not 100% accurate, it is 10x faster than using the V8\nserialize function, which is not available in some environments.\n\n### Example\n\n```ts\nimport { estimateSize } from \"@deno/kv-utils\";\nimport { assertEquals } from \"@std/assert\";\n\nconst value = { a: new Map([[{ a: 1 }, { b: /234/ }]]), b: false };\nassertEquals(estimateSize(value), 36);\n```\n\n## Importing and exporting entries\n\nDeno KV stores can be exported and imported. This is useful for backing up and\nrestoring data, as well as for transferring data between different Deno\nprocesses.\n\nThe import and export utilities are:\n\n- `exportEntries` - Export entries from a Deno KV store as a stream or a\n  response.\n- `importEntries` - Import entries into a Deno KV store.\n\n### Examples\n\nExporting entries from a Deno KV store and saving them to a file:\n\n```ts\nimport { exportEntries } from \"@deno/kv-utils\";\n\nconst db = await Deno.openKv();\nconst file = await Deno.open(\"export.ndjson\", { write: true, create: true });\nfor await (const chunk of exportEntries(db, { prefix: [\"person\"] })) {\n  await file.write(chunk);\n}\nfile.close();\ndb.close();\n```\n\nExporting entries from a Deno KV store and sending them as a response:\n\n```ts ignore\nimport { exportEntries } from \"@deno/kv-utils\";\n\nconst db = await Deno.openKv();\nconst server = Deno.serve((_req) =\u003e\n  exportEntries(\n    db,\n    { prefix: [\"person\"] },\n    { type: \"response\" },\n  )\n);\n\nawait server.finished;\ndb.close();\n```\n\nImporting entries from a file and storing them in a Deno KV store:\n\n```ts\nimport { importEntries } from \"@deno/kv-utils\";\nimport { assert } from \"@std/assert\";\n\nconst db = await Deno.openKv();\nconst file = await Deno.open(\"export.ndjson\", { read: true });\nconst result = await importEntries(db, file.readable);\nassert(result.errors === 0);\ndb.close();\n```\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fkv-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenoland%2Fkv-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoland%2Fkv-utils/lists"}