diff --git a/README.md b/README.md index 4aa3b05..04a755a 100644 --- a/README.md +++ b/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`. diff --git a/deno.json b/deno.json index 6cf2e13..f074146 100644 --- a/deno.json +++ b/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", diff --git a/mod.ts b/mod.ts index dffcc57..e78c448 100644 --- a/mod.ts +++ b/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" diff --git a/src/utils.ts b/src/utils.ts index ad5b4bf..8fa2762 100644 --- a/src/utils.ts +++ b/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(value: Uint8Array) { +export function jsonDeserialize(value: Uint8Array): T { const str = new TextDecoder().decode(value) - return parse(str) + return jsonParse(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(value: string) { +export function jsonParse(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, })