feat: parse

src/index.ts

@@ -1,5 +1,7 @@
 import * as Stringify from './stringify';
+import * as Parse from './parse';
 
 export const JsonKit = {
   ...Stringify,
+  ...Parse,
 } as const;

src/parse.ts

@@ -0,0 +1,171 @@
+import { EJSON } from 'bson';
+import { decompress } from 'lz4-wasm-nodejs';
+
+export type ParseTypeGuardFunction<T> = (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<string, string> };
+  decompress?: boolean | { enable: boolean };
+}
+
+interface _ParseOptions {
+  extended: { enable: boolean; relaxed: boolean };
+  unminify: { enable: boolean; keyMap?: Record<string, string> };
+  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<T = any>(
+  text: string,
+  reviver?: ParseReviverFunction | ParseOptions | null,
+  options?: ParseOptions,
+  typeGuard?: ParseTypeGuardFunction<T>
+): 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<string, string>,
+  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;
+  }
+}

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);
+  });
+});