Merge pull request #200 from oliver-oloughlin/release-0.35.4

chore: increment version, expose json utilities, update docs

README.md

@@ -90,6 +90,11 @@ _Supported Deno verisons:_ **^1.40.0**
     - [With checking](#with-checking)
   - [Document Methods](#document-methods)
     - [flat()](#flat)
+  - [Utility Functions](#utility-functions)
+    - [jsonSerialize()](#jsonserialize)
+    - [jsonDeserialize()](#jsondeserialize)
+    - [jsonStringify()](#jsonstringify)
+    - [jsonParse()](#jsonparse)
   - [Extensions](#extensions)
     - [Zod](#zod)
       - [zodModel()](#zodmodel)
@@ -1233,6 +1238,71 @@ const flattened = doc.flat()
 // }
 ```
 
+## Utility Functions
+
+These are additional utility functions that are exposed and can be used outside
+of `kvdex`.
+
+### jsonSerialize()
+
+Serialize a JSON-like value to a Uint8Array.
+
+```ts
+import { jsonSerialize } from "@olli/kvdex"
+
+const serialized = jsonSerialize({
+  foo: "foo",
+  bar: "bar",
+  bigint: 10n,
+})
+```
+
+### jsonDeserialize()
+
+Deserialize a value that was serialized using `jsonSerialize()`.
+
+```ts
+import { jsonDeserialize, jsonSerialize } from "@olli/kvdex"
+
+const serialized = jsonSerialize({
+  foo: "foo",
+  bar: "bar",
+  bigint: 10n,
+})
+
+const value = jsonDeserialize(serialized)
+```
+
+### jsonStringify()
+
+Stringify a JSON-like value.
+
+```ts
+import { jsonStringify } from "@olli/kvdex"
+
+const str = jsonStringify({
+  foo: "foo",
+  bar: "bar",
+  bigint: 10n,
+})
+```
+
+### jsonParse()
+
+Parse a value that was stringified using `jsonStringify()`
+
+```ts
+import { jsonParse, jsonStringify } from "@olli/kvdex"
+
+const str = jsonStringify({
+  foo: "foo",
+  bar: "bar",
+  bigint: 10n,
+})
+
+const value = jsonParse(str)
+```
+
 ## Extensions
 
 Additional features outside of the basic functionality provided by `kvdex`.

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@olli/kvdex",
-  "version": "0.35.3",
+  "version": "0.35.4",
   "exports": {
     ".": "./mod.ts",
     "./ext/zod": "./ext/zod.ts",

mod.ts

@@ -1,10 +1,18 @@
-// Expose builders and classes
+// Expose constructor functions and classes
 export { model } from "./src/model.ts"
 export { Kvdex, kvdex } from "./src/kvdex.ts"
 export { Collection, collection } from "./src/collection.ts"
 export { AtomicBuilder } from "./src/atomic_builder.ts"
 export { Document } from "./src/document.ts"
 
+// Expose reusable utilities
+export {
+  jsonDeserialize,
+  jsonParse,
+  jsonSerialize,
+  jsonStringify,
+} from "./src/utils.ts"
+
 // Expose errors
 export * from "./src/errors.ts"
 

src/utils.ts

@@ -700,45 +700,93 @@ export function afterDenoCoreDeserialize(value: unknown): unknown {
 }
 
 /**
- * Serialize a value to Uint8Array.
+ * Serialize a JSON-like value to a Uint8Array.
  *
- * @param value . Value to be serialized.
+ * @example
+ * ```ts
+ * import { jsonSerialize } from "@olli/kvdex"
+ *
+ * const serialized = jsonSerialize({
+ *   foo: "foo",
+ *   bar: "bar",
+ *   bigint: 10n
+ * })
+ * ```
+ *
+ * @param value - Value to be serialized.
  * @returns Serialized value.
  */
-export function jsonSerialize(value: unknown) {
-  const str = stringify(value)
+export function jsonSerialize(value: unknown): Uint8Array {
+  const str = jsonStringify(value)
   return new TextEncoder().encode(str)
 }
 
 /**
- * Deserialize a value encoded as Uint8Array.
+ * Deserialize a value that was serialized using `jsonSerialize()`.
+ *
+ * @example
+ * ```ts
+ * import { jsonSerialize, jsonDeserialize } from "@olli/kvdex"
+ *
+ * const serialized = jsonSerialize({
+ *   foo: "foo",
+ *   bar: "bar",
+ *   bigint: 10n
+ * })
+ *
+ * const value = jsonDeserialize(serialized)
+ * ```
  *
  * @param value - Value to be deserialize.
  * @returns Deserialized value.
  */
-export function jsonDeserialize<T>(value: Uint8Array) {
+export function jsonDeserialize<T>(value: Uint8Array): T {
   const str = new TextDecoder().decode(value)
-  return parse<T>(str)
+  return jsonParse<T>(str)
 }
 
 /**
- * Stringify a JSON-like object.
+ * Stringify a JSON-like value.
+ *
+ * @example
+ * ```ts
+ * import { jsonStringify } from "@olli/kvdex"
+ *
+ * const str = jsonStringify({
+ *   foo: "foo",
+ *   bar: "bar",
+ *   bigint: 10n
+ * })
+ * ```
  *
  * @param value
  * @param space
  * @returns
  */
-export function stringify(value: unknown, space?: number | string) {
+export function jsonStringify(value: unknown, space?: number | string): string {
   return JSON.stringify(_replacer(value), replacer, space)
 }
 
 /**
- * Parse a stringified JSON-like object.
+ * Parse a value that was stringified using `jsonStringify()`
+ *
+ * @example
+ * ```ts
+ * import { jsonStringify, jsonParse } from "@olli/kvdex"
+ *
+ * const str = jsonStringify({
+ *   foo: "foo",
+ *   bar: "bar",
+ *   bigint: 10n
+ * })
+ *
+ * const value = jsonParse(str)
+ * ```
  *
  * @param value
  * @returns
  */
-export function parse<T>(value: string) {
+export function jsonParse<T>(value: string): T {
   return postReviver(JSON.parse(value, reviver)) as T
 }
 
@@ -847,7 +895,7 @@ export function _replacer(value: unknown): unknown {
       message: value.message,
       name: value.name,
       stack: value.stack,
-      cause: stringify(value.cause),
+      cause: jsonStringify(value.cause),
     }
     return {
       [TypeKey.Error]: jsonError,
@@ -1009,7 +1057,7 @@ export function _reviver(value: unknown): unknown {
     )
 
     const error = new Error(message, {
-      cause: cause ? parse(cause) : undefined,
+      cause: cause ? jsonParse(cause) : undefined,
       ...rest,
     })