diff --git a/src/index.ts b/src/index.ts index 243ccca..810e153 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1,7 @@ import * as Stringify from './stringify'; +import * as Parse from './parse'; export const JsonKit = { ...Stringify, + ...Parse, } as const; diff --git a/src/parse.ts b/src/parse.ts new file mode 100644 index 0000000..ad7f765 --- /dev/null +++ b/src/parse.ts @@ -0,0 +1,171 @@ +import { EJSON } from 'bson'; +import { decompress } from 'lz4-wasm-nodejs'; + +export type ParseTypeGuardFunction = (obj: any) => obj is T; +export type ParseReviverFunction = (this: any, key: string, value: any) => any; + +export interface ParseOptions { + extended?: boolean | { enable: boolean; relaxed?: boolean }; + unminify?: boolean | { enable: boolean; keyMap?: Record }; + decompress?: boolean | { enable: boolean }; +} + +interface _ParseOptions { + extended: { enable: boolean; relaxed: boolean }; + unminify: { enable: boolean; keyMap?: Record }; + decompress: { enable: boolean }; +} + +const defaultOptions: _ParseOptions = { + extended: { enable: false, relaxed: true }, + unminify: { enable: true, keyMap: undefined }, + decompress: { enable: true }, +}; + +function mergeWithDefaultOptions(input?: ParseOptions): _ParseOptions { + if (input == null) return defaultOptions; + + if (input.extended == null) { + input.extended = defaultOptions.extended; + } else if (typeof input.extended === 'boolean') { + input.extended = { + enable: input.extended, + relaxed: defaultOptions.extended.relaxed, + }; + } else { + input.extended = { + enable: input.extended.enable, + relaxed: input.extended.relaxed ?? defaultOptions.extended.relaxed, + }; + } + + if (input.unminify == null) { + input.unminify = defaultOptions.unminify; + } else if (typeof input.unminify === 'boolean') { + input.unminify = { + enable: input.unminify, + keyMap: defaultOptions.unminify.keyMap, + }; + } else { + input.unminify = { + enable: input.unminify.enable, + keyMap: input.unminify.keyMap ?? defaultOptions.unminify.keyMap, + }; + } + + if (input.decompress == null) { + input.decompress = defaultOptions.decompress; + } else if (typeof input.decompress === 'boolean') { + input.decompress = { + enable: input.decompress, + }; + } else { + input.decompress = { + enable: input.decompress.enable, + }; + } + + return input as _ParseOptions; +} + +export function parse( + text: string, + reviver?: ParseReviverFunction | ParseOptions | null, + options?: ParseOptions, + typeGuard?: ParseTypeGuardFunction +): T { + let _reviver: ParseReviverFunction | undefined = undefined; + if (typeof reviver === 'function') { + _reviver = reviver satisfies ParseReviverFunction; + } else if (options == null) { + options = (reviver ?? undefined) satisfies ParseOptions | undefined; + reviver = undefined; + } + + const _options = mergeWithDefaultOptions(options); + + if (_options.decompress.enable) { + text = decompressString(text); + } + + let result: any; + if (_options.extended.enable) { + /** + * EJSON.parse does not accept reviver function in bson@4.7.2 + * tracking issue at https://jira.mongodb.org/browse/NODE-4497 + */ + result = EJSON.parse(text, { + relaxed: _options.extended.relaxed, + }); + } else { + result = JSON.parse(text, _reviver); + } + + if (_options.unminify.enable) { + result = unminifyKeys(result, _options.unminify.keyMap); + } + + try { + if (typeGuard?.(result) === false) { + throw new Error( + 'Please throw a custom error in the type guard function to track the problems' + ); + } + } catch (err: unknown) { + let errMsg = 'Parsed object faild to pass type guard'; + if (err instanceof Error && err.message?.length > 0) { + errMsg += `\n Reason: ${err.message}`; + } + throw new TypeError(errMsg); + } + return result; +} + +function unminifyKeys( + obj: any, + keyMap?: Record, + level?: number +): any { + let _level: number; + if (level == null || level === 0) { + if (keyMap == null) { + if (obj?._jkv == null || obj?._jkm == null) { + return obj; + } + keyMap = obj._jkm; + } + if (obj?._jkv != null) { + delete obj._jkm; + obj = obj._jkv; + } + _level = 1; + } else { + _level = level + 1; + } + + if (Array.isArray(obj)) { + obj.forEach((o, i) => { + obj[i] = unminifyKeys(o, keyMap, _level); + }); + } else if (obj?.constructor === Object) { + Object.entries(obj).forEach(([key, value]) => { + value = unminifyKeys(value, keyMap, _level); + const originalKey = keyMap?.[key]; + if (typeof originalKey === 'string' && originalKey.length > 0) { + obj[originalKey] = value; + delete obj[key]; + } + }); + } + + return obj; +} + +export function decompressString(str: string): string { + try { + return new TextDecoder().decode(decompress(Buffer.from(str, 'base64'))); + } catch (err: unknown) { + // str is not a base64 encoded string of a byte array + return str; + } +} diff --git a/test/parse.perf.test.ts b/test/parse.perf.test.ts new file mode 100644 index 0000000..412b97b --- /dev/null +++ b/test/parse.perf.test.ts @@ -0,0 +1,116 @@ +import { describe, it } from '@jest/globals'; +import { JsonKit } from '../src'; +import { formatDuration, timer } from './util'; + +const test = (data: any): void => { + const [original, originalStringifyDuration] = timer(() => + JSON.stringify(data) + ); + const [, originalDuration] = timer(() => JSON.parse(original)); + + const [basic, basicStringifyDuration] = timer(() => JsonKit.stringify(data)); + const [, basicDuration] = timer(() => + JsonKit.parse(basic, { unminify: false, decompress: false }) + ); + + const [minified, minifiedStringifyDuration] = timer(() => + JsonKit.stringify(data, { minify: true }) + ); + const [, unminifiedDuration] = timer(() => + JsonKit.parse(minified, { unminify: true, decompress: false }) + ); + + const [compressed, compressedStringifyDuration] = timer(() => + JsonKit.stringify(data, { compress: true }) + ); + const [, decompressedDuration] = timer(() => + JsonKit.parse(compressed, { unminify: false, decompress: true }) + ); + + const [minifiedAndCompressed, minifiedAndCompressedStringifyDuration] = timer( + () => + JsonKit.stringify(data, { + minify: true, + compress: true, + }) + ); + const [, unminifiedAndDecompressedDuration] = timer(() => + JsonKit.parse(minifiedAndCompressed, { + unminify: true, + decompress: true, + }) + ); + + console.info( + `baseline: [parse: ${formatDuration( + originalDuration + )} (±0.00%)] [stringify: ${formatDuration( + originalStringifyDuration + )} (±0.00%)]` + ); + + console.info( + `basic: [parse: ${formatDuration(basicDuration)} (${( + ((basicDuration - originalDuration) / originalDuration) * + 100 + ).toFixed(2)}%)] [stringify: ${formatDuration(basicStringifyDuration)} (${( + ((basicStringifyDuration - originalStringifyDuration) / + originalStringifyDuration) * + 100 + ).toFixed(2)}%)]` + ); + + console.info( + `unminify: [parse: ${formatDuration(unminifiedDuration)} (${( + ((unminifiedDuration - originalDuration) / originalDuration) * + 100 + ).toFixed(2)}%)] [stringify: ${formatDuration( + minifiedStringifyDuration + )} (${( + ((minifiedStringifyDuration - originalStringifyDuration) / + originalStringifyDuration) * + 100 + ).toFixed(2)}%)]` + ); + + console.info( + `decompress: [parse: ${formatDuration(decompressedDuration)} (${( + ((decompressedDuration - originalDuration) / originalDuration) * + 100 + ).toFixed(2)}%)] [stringify: ${formatDuration( + compressedStringifyDuration + )} (${( + ((compressedStringifyDuration - originalStringifyDuration) / + originalStringifyDuration) * + 100 + ).toFixed(2)}%)]` + ); + + console.info( + `unminify + decompress: [parse: ${formatDuration( + unminifiedAndDecompressedDuration + )} (${( + ((unminifiedAndDecompressedDuration - originalDuration) / + originalDuration) * + 100 + ).toFixed(2)}%)] [stringify: ${formatDuration( + minifiedAndCompressedStringifyDuration + )} (${( + ((minifiedAndCompressedStringifyDuration - originalStringifyDuration) / + originalStringifyDuration) * + 100 + ).toFixed(2)}%)]` + ); +}; + +describe('[parse] performance', () => { + it('parse with ~650KB json data', async () => { + const data = await import('./dataset/ne_110m_populated_places.json'); + test(data); + }); + + it('parse with ~50MB json data', async () => { + const data = await import('./dataset/ne_10m_roads.json'); + test(data); + }); +}); diff --git a/test/parse.test.ts b/test/parse.test.ts new file mode 100644 index 0000000..1dc4ee6 --- /dev/null +++ b/test/parse.test.ts @@ -0,0 +1,210 @@ +import { describe, expect, it } from '@jest/globals'; +import { EJSON } from 'bson'; +import { JsonKit } from '../src'; +import type { ParseReviverFunction } from '../src/parse'; + +describe('[parse] basic', () => { + const text = + '{"2":"2","a":1,"":true," ":null,"arr":[1,"2",true,null,[],{}],"nested":{"2":"2","a":1},"empty":{}}'; + + it('parse should have identical behavior as built-in JSON.parse', () => { + const reviver: ParseReviverFunction = () => 'test'; + + expect(JsonKit.parse(text)).toStrictEqual(JSON.parse(text)); + + expect(JsonKit.parse(text, reviver)).toStrictEqual( + JSON.parse(text, reviver) + ); + }); + + it('parse should have identical behavior as bson.EJSON.parse', () => { + const reviver: ParseReviverFunction = () => 'test'; + + expect( + JsonKit.parse(text, { extended: { enable: true, relaxed: false } }) + ).toStrictEqual(EJSON.parse(text, { relaxed: false })); + + expect( + JsonKit.parse(text, { extended: { enable: true, relaxed: true } }) + ).toStrictEqual(EJSON.parse(text, { relaxed: true })); + + expect(JsonKit.parse(text, reviver, { extended: true })).toStrictEqual( + EJSON.parse(text) + ); + }); + + it('parse default options should match docs', () => { + const base = JsonKit.parse(text); + const emptyOptions = JsonKit.parse(text, {}); + const optionsShorthand = JsonKit.parse(text, { + extended: true, + unminify: false, + decompress: false, + }); + const optionsFull = JsonKit.parse(text, { + extended: { enable: false }, + unminify: { enable: true }, + decompress: { enable: true }, + }); + const optionsDefaultFull = JsonKit.parse(text, { + extended: { enable: true, relaxed: true }, + unminify: { enable: false, keyMap: undefined }, + decompress: { enable: false }, + }); + const defaultOptions = JsonKit.parse(text, { + extended: { enable: false, relaxed: true }, + unminify: { enable: true, keyMap: undefined }, + decompress: { enable: true }, + }); + + expect(base).toStrictEqual(defaultOptions); + + expect(emptyOptions).toStrictEqual(defaultOptions); + + expect(optionsShorthand).toStrictEqual(optionsDefaultFull); + + expect(optionsFull).toStrictEqual(defaultOptions); + }); +}); + +describe('[parse] unminify', () => { + const obj = { + 'very-long-name': { + 'very-long-name': 'very-long-name', + 'very-long-name-2': 2, + }, + arr: [ + { 'very-long-name': { 'very-long-name': 'very-long-name' } }, + { 'very-long-name-2': true }, + ], + normal: 'string', + }; + + it('parse unminify without keyMap', () => { + const text = + '{"_jkv":{"normal":"string","a0":{"a0":"very-long-name","a1":2},"arr":[{"a0":{"a0":"very-long-name"}},{"a1":true}]},"_jkm":{"a0":"very-long-name","a1":"very-long-name-2"}}'; + expect( + JsonKit.parse(text, (key, value) => (key !== 'arr' ? value : undefined), { + unminify: { enable: true, keyMap: undefined }, + }) + ).toStrictEqual({ + 'very-long-name': obj['very-long-name'], + normal: obj['normal'], + }); + }); + + it('parse unminify with keyMap', () => { + const text = + '{"_jkv":{"arr":[{"vln":{"vln":"very-long-name"}},{"vln2":true}],"normal":"string","vln":{"vln":"very-long-name","vln2":2}},"_jkm":{"vln":"very-long-name","vln2":"very-long-name-2"}}'; + expect( + JsonKit.parse(text, { + unminify: { + enable: true, + keyMap: { vln: 'very-long-name', vln2: 'very-long-name-2' }, + }, + }) + ).toStrictEqual(obj); + }); +}); + +describe('[parse] decompress', () => { + const obj = { + a: 1, + '2': '2', + '': true, + ' ': null, + 'a-b': undefined, + _c: new Date(), + toString: () => 'string', + arr: [1, '2', true, null, undefined, new Date(), () => 'string', [], {}], + nested: { + a: 1, + '2': '2', + }, + empty: {}, + }; + + it('parse with decompression should have identical behavior as decompression and built-in JSON.stringify', () => { + const text = JsonKit.stringify(obj, { compress: true }); + + const reviver: ParseReviverFunction = () => 'test'; + + expect(JsonKit.parse(text, { decompress: true })).toStrictEqual( + JSON.parse(JsonKit.decompressString(text)) + ); + + expect(JsonKit.parse(text, reviver, { decompress: true })).toStrictEqual( + JSON.parse(JsonKit.decompressString(text), reviver) + ); + }); + + it('parse with decompression should have identical behavior as decompression and bson.EJSON.stringify', () => { + const text = JsonKit.stringify(obj, { + extended: { enable: true, relaxed: false }, + compress: true, + }); + const textRelaxed = JsonKit.stringify(obj, { + extended: { enable: true, relaxed: true }, + compress: true, + }); + + const reviver: ParseReviverFunction = () => 'test'; + + expect( + JsonKit.parse(text, { + extended: { enable: true, relaxed: false }, + decompress: { enable: true }, + }) + ).toStrictEqual( + EJSON.parse(JsonKit.decompressString(text), { relaxed: false }) + ); + + expect( + JsonKit.parse(textRelaxed, { + extended: { enable: true, relaxed: true }, + decompress: { enable: true }, + }) + ).toStrictEqual( + EJSON.parse(JsonKit.decompressString(textRelaxed), { relaxed: true }) + ); + + expect( + JsonKit.parse(textRelaxed, reviver, { extended: true, decompress: true }) + ).toStrictEqual(EJSON.parse(JsonKit.decompressString(textRelaxed))); + }); +}); + +describe('[parse] type guard', () => { + interface TestObject { + a: number; + b: string; + } + + const typeGuard = (obj: any): obj is TestObject => { + return typeof obj?.a === 'number' && typeof obj?.b === 'string'; + }; + + it('parse with type guard passing', () => { + const text = '{"a":1,"b":"2"}'; + expect(() => + JsonKit.parse( + text, + null, + { extended: false, unminify: false, decompress: false }, + typeGuard + ) + ).not.toThrow(); + }); + + it('parse with type guard throwing', () => { + const text = '{"a":"1","b":"2"}'; + expect(() => + JsonKit.parse( + text, + null, + { extended: false, unminify: false, decompress: false }, + typeGuard + ) + ).toThrow(); + }); +});