seroval 1.0.3 → 1.0.4

package/src/core/context/serializer.ts

@@ -6,6 +6,11 @@ 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';
@@ -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/errors.ts

@@ -0,0 +1,99 @@
+import { serializeString } from './string';
+import { 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/reference.ts

@@ -1,5 +1,9 @@
 import assert from './utils/assert';
 import { REFERENCES_KEY } from './keys';
+import {
+  SerovalMissingReferenceError,
+  SerovalMissingReferenceForIdError,
+} from '..';
 
 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/serializer.ts

@@ -9,6 +9,7 @@ import BaseSerializerContext from '../context/serializer';
 import getIdentifier from '../utils/get-identifier';
 import type { SerovalMode } from '../plugin';
 import { SerovalNodeType } from '../constants';
+import { SerovalUnsupportedNodeError } from '../errors';
 
 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/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) + '"');
-  }
-}