seroval 1.0.3 → 1.0.5

package/src/core/context/serializer.ts

@@ -6,45 +6,50 @@ import {
   SerovalNodeType,
   SerovalObjectFlags,
 } from '../constants';
+import {
+  SerovalMissingPluginError,
+  SerovalSerializationError,
+  SerovalUnsupportedNodeError,
+} from '../errors';
 import { REFERENCES_KEY } from '../keys';
 import type { Plugin, PluginAccessOptions, SerovalMode } from '../plugin';
 import { SpecialReference } from '../special-reference';
 import type {
+  SerovalAggregateErrorNode,
+  SerovalArrayBufferNode,
   SerovalArrayNode,
+  SerovalAsyncIteratorFactoryInstanceNode,
+  SerovalAsyncIteratorFactoryNode,
+  SerovalBigIntTypedArrayNode,
+  SerovalBoxedNode,
+  SerovalDataViewNode,
+  SerovalDateNode,
+  SerovalErrorNode,
   SerovalIndexedValueNode,
+  SerovalIteratorFactoryInstanceNode,
+  SerovalIteratorFactoryNode,
+  SerovalMapNode,
   SerovalNode,
+  SerovalNodeWithID,
+  SerovalNullConstructorNode,
+  SerovalObjectNode,
   SerovalObjectRecordKey,
   SerovalObjectRecordNode,
-  SerovalReferenceNode,
-  SerovalObjectNode,
-  SerovalNullConstructorNode,
-  SerovalRegExpNode,
-  SerovalDateNode,
-  SerovalSetNode,
-  SerovalMapNode,
-  SerovalArrayBufferNode,
-  SerovalTypedArrayNode,
-  SerovalBigIntTypedArrayNode,
-  SerovalDataViewNode,
-  SerovalAggregateErrorNode,
-  SerovalErrorNode,
-  SerovalPromiseNode,
-  SerovalWKSymbolNode,
-  SerovalBoxedNode,
   SerovalPluginNode,
   SerovalPromiseConstructorNode,
-  SerovalPromiseResolveNode,
+  SerovalPromiseNode,
   SerovalPromiseRejectNode,
-  SerovalIteratorFactoryInstanceNode,
-  SerovalIteratorFactoryNode,
-  SerovalAsyncIteratorFactoryInstanceNode,
-  SerovalAsyncIteratorFactoryNode,
+  SerovalPromiseResolveNode,
+  SerovalReferenceNode,
+  SerovalRegExpNode,
+  SerovalSetNode,
   SerovalSpecialReferenceNode,
-  SerovalNodeWithID,
   SerovalStreamConstructorNode,
   SerovalStreamNextNode,
-  SerovalStreamThrowNode,
   SerovalStreamReturnNode,
+  SerovalStreamThrowNode,
+  SerovalTypedArrayNode,
+  SerovalWKSymbolNode,
 } from '../types';
 import { isValidIdentifier } from '../utils/is-valid-identifier';
 
@@ -446,19 +451,19 @@ export default abstract class BaseSerializerContext
   ): string {
     if (typeof key === 'string') {
       const check = Number(key);
-      const isIdentifier = (
+      const isIdentifier =
         // Test if key is a valid positive number or JS identifier
         // so that we don't have to serialize the key and wrap with brackets
-        check >= 0
-        // It's also important to consider that if the key is
-        // indeed numeric, we need to make sure that when
-        // converted back into a string, it's still the same
-        // to the original key. This allows us to differentiate
-        // keys that has numeric formats but in a different
-        // format, which can cause unintentional key declaration
-        // Example: { 0x1: 1 } vs { '0x1': 1 }
-        && check.toString() === key
-      ) || isValidIdentifier(key);
+        (check >= 0 &&
+          // It's also important to consider that if the key is
+          // indeed numeric, we need to make sure that when
+          // converted back into a string, it's still the same
+          // to the original key. This allows us to differentiate
+          // keys that has numeric formats but in a different
+          // format, which can cause unintentional key declaration
+          // Example: { 0x1: 1 } vs { '0x1': 1 }
+          check.toString() === key) ||
+        isValidIdentifier(key);
       if (this.isIndexedValueInStack(val)) {
         const refParam = this.getRefParam((val as SerovalIndexedValueNode).i);
         this.markRef(source.i);
@@ -528,19 +533,19 @@ export default abstract class BaseSerializerContext
   ): void {
     const serialized = this.serialize(value);
     const check = Number(key);
-    const isIdentifier = (
+    const isIdentifier =
       // Test if key is a valid positive number or JS identifier
       // so that we don't have to serialize the key and wrap with brackets
-      check >= 0
-      // It's also important to consider that if the key is
-      // indeed numeric, we need to make sure that when
-      // converted back into a string, it's still the same
-      // to the original key. This allows us to differentiate
-      // keys that has numeric formats but in a different
-      // format, which can cause unintentional key declaration
-      // Example: { 0x1: 1 } vs { '0x1': 1 }
-      && check.toString() === key
-    ) || isValidIdentifier(key);
+      (check >= 0 &&
+        // It's also important to consider that if the key is
+        // indeed numeric, we need to make sure that when
+        // converted back into a string, it's still the same
+        // to the original key. This allows us to differentiate
+        // keys that has numeric formats but in a different
+        // format, which can cause unintentional key declaration
+        // Example: { 0x1: 1 } vs { '0x1': 1 }
+        check.toString() === key) ||
+      isValidIdentifier(key);
     if (this.isIndexedValueInStack(value)) {
       // Strict identifier check, make sure
       // that it isn't numeric (except NaN)
@@ -899,7 +904,7 @@ export default abstract class BaseSerializerContext
         }
       }
     }
-    throw new Error('Missing plugin for tag "' + node.c + '".');
+    throw new SerovalMissingPluginError(node.c);
   }
 
   private getConstructor(node: SerovalNodeWithID): string {
@@ -1155,78 +1160,82 @@ export default abstract class BaseSerializerContext
   }
 
   serialize(node: SerovalNode): string {
-    switch (node.t) {
-      case SerovalNodeType.Constant:
-        return CONSTANT_STRING[node.s];
-      case SerovalNodeType.Number:
-        return '' + node.s;
-      case SerovalNodeType.String:
-        return '"' + node.s + '"';
-      case SerovalNodeType.BigInt:
-        return node.s + 'n';
-      case SerovalNodeType.IndexedValue:
-        return this.getRefParam(node.i);
-      case SerovalNodeType.Reference:
-        return this.serializeReference(node);
-      case SerovalNodeType.Array:
-        return this.serializeArray(node);
-      case SerovalNodeType.Object:
-        return this.serializeObject(node);
-      case SerovalNodeType.NullConstructor:
-        return this.serializeNullConstructor(node);
-      case SerovalNodeType.Date:
-        return this.serializeDate(node);
-      case SerovalNodeType.RegExp:
-        return this.serializeRegExp(node);
-      case SerovalNodeType.Set:
-        return this.serializeSet(node);
-      case SerovalNodeType.Map:
-        return this.serializeMap(node);
-      case SerovalNodeType.ArrayBuffer:
-        return this.serializeArrayBuffer(node);
-      case SerovalNodeType.BigIntTypedArray:
-      case SerovalNodeType.TypedArray:
-        return this.serializeTypedArray(node);
-      case SerovalNodeType.DataView:
-        return this.serializeDataView(node);
-      case SerovalNodeType.AggregateError:
-        return this.serializeAggregateError(node);
-      case SerovalNodeType.Error:
-        return this.serializeError(node);
-      case SerovalNodeType.Promise:
-        return this.serializePromise(node);
-      case SerovalNodeType.WKSymbol:
-        return this.serializeWellKnownSymbol(node);
-      case SerovalNodeType.Boxed:
-        return this.serializeBoxed(node);
-      case SerovalNodeType.PromiseConstructor:
-        return this.serializePromiseConstructor(node);
-      case SerovalNodeType.PromiseResolve:
-        return this.serializePromiseResolve(node);
-      case SerovalNodeType.PromiseReject:
-        return this.serializePromiseReject(node);
-      case SerovalNodeType.Plugin:
-        return this.serializePlugin(node);
-      case SerovalNodeType.SpecialReference:
-        return this.serializeSpecialReference(node);
-      case SerovalNodeType.IteratorFactory:
-        return this.serializeIteratorFactory(node);
-      case SerovalNodeType.IteratorFactoryInstance:
-        return this.serializeIteratorFactoryInstance(node);
-      case SerovalNodeType.AsyncIteratorFactory:
-        return this.serializeAsyncIteratorFactory(node);
-      case SerovalNodeType.AsyncIteratorFactoryInstance:
-        return this.serializeAsyncIteratorFactoryInstance(node);
-      case SerovalNodeType.StreamConstructor:
-        return this.serializeStreamConstructor(node);
-      case SerovalNodeType.StreamNext:
-        return this.serializeStreamNext(node);
-      case SerovalNodeType.StreamThrow:
-        return this.serializeStreamThrow(node);
-      case SerovalNodeType.StreamReturn:
-        return this.serializeStreamReturn(node);
-      default:
-        throw new Error('invariant');
+    try {
+      switch (node.t) {
+        case SerovalNodeType.Constant:
+          return CONSTANT_STRING[node.s];
+        case SerovalNodeType.Number:
+          return '' + node.s;
+        case SerovalNodeType.String:
+          return '"' + node.s + '"';
+        case SerovalNodeType.BigInt:
+          return node.s + 'n';
+        case SerovalNodeType.IndexedValue:
+          return this.getRefParam(node.i);
+        case SerovalNodeType.Reference:
+          return this.serializeReference(node);
+        case SerovalNodeType.Array:
+          return this.serializeArray(node);
+        case SerovalNodeType.Object:
+          return this.serializeObject(node);
+        case SerovalNodeType.NullConstructor:
+          return this.serializeNullConstructor(node);
+        case SerovalNodeType.Date:
+          return this.serializeDate(node);
+        case SerovalNodeType.RegExp:
+          return this.serializeRegExp(node);
+        case SerovalNodeType.Set:
+          return this.serializeSet(node);
+        case SerovalNodeType.Map:
+          return this.serializeMap(node);
+        case SerovalNodeType.ArrayBuffer:
+          return this.serializeArrayBuffer(node);
+        case SerovalNodeType.BigIntTypedArray:
+        case SerovalNodeType.TypedArray:
+          return this.serializeTypedArray(node);
+        case SerovalNodeType.DataView:
+          return this.serializeDataView(node);
+        case SerovalNodeType.AggregateError:
+          return this.serializeAggregateError(node);
+        case SerovalNodeType.Error:
+          return this.serializeError(node);
+        case SerovalNodeType.Promise:
+          return this.serializePromise(node);
+        case SerovalNodeType.WKSymbol:
+          return this.serializeWellKnownSymbol(node);
+        case SerovalNodeType.Boxed:
+          return this.serializeBoxed(node);
+        case SerovalNodeType.PromiseConstructor:
+          return this.serializePromiseConstructor(node);
+        case SerovalNodeType.PromiseResolve:
+          return this.serializePromiseResolve(node);
+        case SerovalNodeType.PromiseReject:
+          return this.serializePromiseReject(node);
+        case SerovalNodeType.Plugin:
+          return this.serializePlugin(node);
+        case SerovalNodeType.SpecialReference:
+          return this.serializeSpecialReference(node);
+        case SerovalNodeType.IteratorFactory:
+          return this.serializeIteratorFactory(node);
+        case SerovalNodeType.IteratorFactoryInstance:
+          return this.serializeIteratorFactoryInstance(node);
+        case SerovalNodeType.AsyncIteratorFactory:
+          return this.serializeAsyncIteratorFactory(node);
+        case SerovalNodeType.AsyncIteratorFactoryInstance:
+          return this.serializeAsyncIteratorFactoryInstance(node);
+        case SerovalNodeType.StreamConstructor:
+          return this.serializeStreamConstructor(node);
+        case SerovalNodeType.StreamNext:
+          return this.serializeStreamNext(node);
+        case SerovalNodeType.StreamThrow:
+          return this.serializeStreamThrow(node);
+        case SerovalNodeType.StreamReturn:
+          return this.serializeStreamReturn(node);
+        default:
+          throw new SerovalUnsupportedNodeError(node);
+      }
+    } catch (error) {
+      throw new SerovalSerializationError(error);
     }
   }
 }

package/src/core/cross/async.ts

@@ -1,6 +1,6 @@
 import BaseAsyncParserContext from '../context/parser/async';
-import type { CrossParserContextOptions } from './parser';
 import type { SerovalMode } from '../plugin';
+import type { CrossParserContextOptions } from './parser';
 
 export type CrossAsyncParserContextOptions = CrossParserContextOptions;
 

package/src/core/cross/deserializer.ts

@@ -1,5 +1,5 @@
-import BaseDeserializerContext from '../context/deserializer';
 import type { BaseDeserializerOptions } from '../context/deserializer';
+import BaseDeserializerContext from '../context/deserializer';
 import type { SerovalMode } from '../plugin';
 
 export type CrossDeserializerContextOptions = BaseDeserializerOptions;

package/src/core/cross/serializer.ts

@@ -1,9 +1,9 @@
-import type { SerovalNode } from '../types';
-import { GLOBAL_CONTEXT_REFERENCES } from '../keys';
 import type { BaseSerializerContextOptions } from '../context/serializer';
 import BaseSerializerContext from '../context/serializer';
+import { GLOBAL_CONTEXT_REFERENCES } from '../keys';
 import type { SerovalMode } from '../plugin';
 import { serializeString } from '../string';
+import type { SerovalNode } from '../types';
 import type { CrossContextOptions } from './parser';
 
 export interface CrossSerializerContextOptions

package/src/core/errors.ts

@@ -0,0 +1,102 @@
+import { serializeString } from './string';
+import type { SerovalNode } from './types';
+
+const { toString: objectToString } = /* @__PURE__ */ Object.prototype;
+
+function getErrorMessage(type: string, cause: any): string {
+  if (cause instanceof Error) {
+    return `Seroval caught an error during the ${type} process.
+  
+${cause.name}
+${cause.message}
+
+- For more information, please check the "cause" property of this error.
+- If you believe this is an error in Seroval, please submit an issue at https://github.com/lxsmnsyc/seroval/issues/new`;
+  }
+  return `Seroval caught an error during the ${type} process.
+
+"${objectToString.call(cause)}"
+
+For more information, please check the "cause" property of this error.`;
+}
+
+export class SerovalError extends Error {
+  constructor(
+    type: string,
+    public cause: any,
+  ) {
+    super(getErrorMessage(type, cause));
+  }
+}
+
+export class SerovalParserError extends SerovalError {
+  constructor(cause: any) {
+    super('parsing', cause);
+  }
+}
+
+export class SerovalSerializationError extends SerovalError {
+  constructor(cause: any) {
+    super('serialization', cause);
+  }
+}
+
+export class SerovalDeserializationError extends SerovalError {
+  constructor(cause: any) {
+    super('deserialization', cause);
+  }
+}
+
+export class SerovalUnsupportedTypeError extends Error {
+  constructor(public value: unknown) {
+    super(
+      `The value ${objectToString.call(value)} of type "${typeof value}" cannot be parsed/serialized.
+      
+There are few workarounds for this problem:
+- Transform the value in a way that it can be serialized.
+- If the reference is present on multiple runtimes (isomorphic), you can use the Reference API to map the references.`,
+    );
+  }
+}
+
+export class SerovalUnsupportedNodeError extends Error {
+  constructor(node: SerovalNode) {
+    super('Unsupported node type "' + node.t + '".');
+  }
+}
+
+export class SerovalMissingPluginError extends Error {
+  constructor(tag: string) {
+    super('Missing plugin for tag "' + tag + '".');
+  }
+}
+
+export class SerovalMissingInstanceError extends Error {
+  constructor(tag: string) {
+    super('Missing "' + tag + '" instance.');
+  }
+}
+
+export class SerovalMissingReferenceError extends Error {
+  constructor(public value: unknown) {
+    super(
+      'Missing reference for the value "' +
+        objectToString.call(value) +
+        '" of type "' +
+        typeof value +
+        '"',
+    );
+  }
+}
+
+export class SerovalMissingReferenceForIdError extends Error {
+  constructor(id: string) {
+    super('Missing reference for id "' + serializeString(id) + '"');
+  }
+}
+
+export class SerovalUnknownTypedArrayError extends Error {
+  constructor(name: string) {
+    super('Unknown TypedArray "' + name + '"');
+  }
+}

package/src/core/literals.ts

@@ -31,12 +31,12 @@ export const NULL_NODE = /* @__PURE__ */ createConstantNode(
   SerovalConstant.Null,
 );
 export const NEG_ZERO_NODE = /* @__PURE__ */ createConstantNode(
-  SerovalConstant.NegativeZero,
+  SerovalConstant.NegZero,
 );
 export const INFINITY_NODE = /* @__PURE__ */ createConstantNode(
-  SerovalConstant.Infinity,
+  SerovalConstant.Inf,
 );
 export const NEG_INFINITY_NODE = /* @__PURE__ */ createConstantNode(
-  SerovalConstant.NegativeInfinity,
+  SerovalConstant.NegInf,
 );
-export const NAN_NODE = /* @__PURE__ */ createConstantNode(SerovalConstant.NaN);
+export const NAN_NODE = /* @__PURE__ */ createConstantNode(SerovalConstant.Nan);

package/src/core/plugin.ts

@@ -1,8 +1,8 @@
+import type BaseDeserializerContext from './context/deserializer';
 import type BaseAsyncParserContext from './context/parser/async';
 import type BaseStreamParserContext from './context/parser/stream';
 import type BaseSyncParserContext from './context/parser/sync';
 import type BaseSerializerContext from './context/serializer';
-import type BaseDeserializerContext from './context/deserializer';
 
 export type SerovalMode = 'vanilla' | 'cross';
 

package/src/core/reference.ts

@@ -1,5 +1,9 @@
-import assert from './utils/assert';
+import {
+  SerovalMissingReferenceError,
+  SerovalMissingReferenceForIdError,
+} from '..';
 import { REFERENCES_KEY } from './keys';
+import assert from './utils/assert';
 
 const REFERENCE = new Map<unknown, string>();
 const INV_REFERENCE = new Map<string, unknown>();
@@ -19,12 +23,12 @@ export function hasReference(id: string): boolean {
 }
 
 export function getReferenceID<T>(value: T): string {
-  assert(hasReferenceID(value), new Error('Missing reference id'));
+  assert(hasReferenceID(value), new SerovalMissingReferenceError(value));
   return REFERENCE.get(value)!;
 }
 
 export function getReference<T>(id: string): T {
-  assert(hasReference(id), new Error('Missing reference for id:' + id));
+  assert(hasReference(id), new SerovalMissingReferenceForIdError(id));
   return INV_REFERENCE.get(id) as T;
 }
 

package/src/core/tree/async.ts

@@ -1,5 +1,5 @@
-import BaseAsyncParserContext from '../context/parser/async';
 import type { BaseParserContextOptions } from '../context/parser';
+import BaseAsyncParserContext from '../context/parser/async';
 import type { SerovalMode } from '../plugin';
 
 export type AsyncParserContextOptions = Omit<BaseParserContextOptions, 'refs'>;

package/src/core/tree/deserializer.ts

@@ -1,5 +1,5 @@
-import BaseDeserializerContext from '../context/deserializer';
 import type { BaseDeserializerOptions } from '../context/deserializer';
+import BaseDeserializerContext from '../context/deserializer';
 import type { SerovalMode } from '../plugin';
 
 export interface VanillaDeserializerContextOptions

package/src/core/tree/index.ts

@@ -85,7 +85,10 @@ export async function toJSONAsync<T>(
   };
 }
 
-export function compileJSON(source: SerovalJSON, options: PluginAccessOptions = {}): string {
+export function compileJSON(
+  source: SerovalJSON,
+  options: PluginAccessOptions = {},
+): string {
   const plugins = resolvePlugins(options.plugins);
   const ctx = new VanillaSerializerContext({
     plugins,
@@ -95,7 +98,10 @@ export function compileJSON(source: SerovalJSON, options: PluginAccessOptions =
   return ctx.serializeTop(source.t);
 }
 
-export function fromJSON<T>(source: SerovalJSON, options: PluginAccessOptions = {}): T {
+export function fromJSON<T>(
+  source: SerovalJSON,
+  options: PluginAccessOptions = {},
+): T {
   const plugins = resolvePlugins(options.plugins);
   const ctx = new VanillaDeserializerContext({
     plugins,

package/src/core/tree/serializer.ts

@@ -1,14 +1,15 @@
+import { SerovalNodeType } from '../constants';
+import type { BaseSerializerContextOptions } from '../context/serializer';
+import BaseSerializerContext from '../context/serializer';
+import { SerovalUnsupportedNodeError } from '../errors';
+import type { SerovalMode } from '../plugin';
 import type {
   SerovalNode,
   SerovalPromiseConstructorNode,
   SerovalPromiseRejectNode,
   SerovalPromiseResolveNode,
 } from '../types';
-import type { BaseSerializerContextOptions } from '../context/serializer';
-import BaseSerializerContext from '../context/serializer';
 import getIdentifier from '../utils/get-identifier';
-import type { SerovalMode } from '../plugin';
-import { SerovalNodeType } from '../constants';
 
 export type VanillaSerializerContextOptions = BaseSerializerContextOptions;
 
@@ -61,15 +62,15 @@ export default class VanillaSerializerContext extends BaseSerializerContext {
   protected serializePromiseConstructor(
     node: SerovalPromiseConstructorNode,
   ): string {
-    throw new Error('Unsupported node type "' + node.t + '".');
+    throw new SerovalUnsupportedNodeError(node);
   }
 
   protected serializePromiseResolve(node: SerovalPromiseResolveNode): string {
-    throw new Error('Unsupported node type "' + node.t + '".');
+    throw new SerovalUnsupportedNodeError(node);
   }
 
   protected serializePromiseReject(node: SerovalPromiseRejectNode): string {
-    throw new Error('Unsupported node type "' + node.t + '".');
+    throw new SerovalUnsupportedNodeError(node);
   }
 
   serializeTop(tree: SerovalNode): string {

package/src/core/types.ts

@@ -1,9 +1,9 @@
 import type {
+  ErrorConstructorTag,
+  SerovalConstant,
   SerovalNodeType,
   SerovalObjectFlags,
-  SerovalConstant,
   Symbols,
-  ErrorConstructorTag,
 } from './constants';
 import type { SpecialReference } from './special-reference';
 

package/src/core/utils/typed-array.ts

@@ -1,3 +1,5 @@
+import { SerovalUnknownTypedArrayError } from '../errors';
+
 type TypedArrayConstructor =
   | Int8ArrayConstructor
   | Int16ArrayConstructor
@@ -49,6 +51,6 @@ export function getTypedArrayConstructor(name: string): TypedArrayConstructor {
     case 'BigUint64Array':
       return BigUint64Array;
     default:
-      throw new Error(`Unknown TypedArray "${name}"`);
+      throw new SerovalUnknownTypedArrayError(name);
   }
 }

package/src/index.ts

@@ -13,3 +13,4 @@ export type { Stream } from './core/stream';
 export { createStream } from './core/stream';
 
 export type { SerovalNode } from './core/types';
+export * from './core/errors';

package/dist/types/core/UnsupportedTypeError.d.ts

@@ -1,5 +0,0 @@
-export default class UnsupportedTypeError extends Error {
-    value: unknown;
-    constructor(value: unknown);
-}
-//# sourceMappingURL=UnsupportedTypeError.d.ts.map

package/dist/types/core/UnsupportedTypeError.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"UnsupportedTypeError.d.ts","sourceRoot":"","sources":["../../../src/core/UnsupportedTypeError.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,OAAO,oBAAqB,SAAQ,KAAK;IAClC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;CAGlC"}

package/src/core/UnsupportedTypeError.ts

@@ -1,7 +0,0 @@
-const { toString: objectToString } = /* @__PURE__ */ Object.prototype;
-
-export default class UnsupportedTypeError extends Error {
-  constructor(public value: unknown) {
-    super('Unsupported type "' + objectToString.call(value) + '"');
-  }
-}