Proposal: Add registerSerializableClass for classes with toSuperJSON() + static fromSuperJSON()

[ZiadTaha62]

Summary

This proposal adds a dedicated, lightweight API that mirrors the existing registerClass pattern but uses class’s defined toSuperJSON/fromSuperJSON methods.

---

Motivation

current implementation of class registry ask for allowedProps to include them in serialization:

import { registerClass } from 'superjson';

class User {
  constructor(public name: string, public createdOn: Date) {}
}

registerClass(User, {
  identifier: 'User',
  allowProps: ['name', 'createdOn'],
});

then re-create instance using Object.assign. This approach works in most cases but has some limitations, as discussed in issue #331, also if class needs to run constructor to initialize some properties or if we want to add fields in our json that are not present as a property in the class.

I think that allow passing explicit to/from methods will solve these problems entirely and add flexible control of serialization, so earlier code becomes:

import { registerSerializableClass, SuperJSONValue } from 'superjson';

class User {
  constructor(public name: string, public createdOn: Date) {}

  static fromSuperJSON(json: SuperJSONValue) {
    return new User(json.name, json.createdOn);
  }

  toSuperJSON(): SuperJSONValue {
    return { name: this.name, createdOn: this.createdOn };
  }
}

registerSerializableClass(User, 'User');

More advanced usage (constructor side-effects, computed fields, json data wrappers):

class User {
  ctorInitializedProp: unknown;

  constructor(public name: string, public createdOn: Date) {
    // Initialize property
    ctorInitializedProp = 'some value';
    // Some side effect on creation
    sideEffect();
  }

  static fromSuperJSON(json: SuperJSONValue) {
    const { data } = json;
    return new User(data.name, data.createdOn);
  }

  toSuperJSON(): SuperJSONValue {
    return {
      label: 'USER',
      date: new Date(),
      data: { name: this.name, createdOn: this.createdOn },
    };
  }
}

As class registry it works for nested classes as well:

class Admin {
  constructor(public adminId: string, user: User) {} // Our earlier serializable class

  static fromSuperJSON(json: SuperJSONValue) {
    return new Admin(json.adminId, json.user);
  }

  toSuperJSON() {
    return { adminId: this.adminId, user: this.user };
  }
}

This completely optional for devs who need more control, as change is additive only (extra single composite Rule).

---

Proposed API

interface SerializableClass {
  static fromSuperJSON(json: SuperJSONValue): InstanceType<this>;
  new (...args: any[]): { toSuperJSON(): SuperJSONValue };
}

SuperJSON.registerSerializableClass(Class);
SuperJSON.registerSerializableClass(Class, 'id'); // or with custom identifier

(Exact same style as the existing registerClass and registerSymbol.)

---

Example

import { SuperJSON } from 'superjson';

// Following convention so our classes can be serialized by other external libs if needed
class JsonSerializable {
  static fromJSON(json: any) {
    return SuperJSON.deserialize(json);
  }
  toJSON() {
    return SuperJSON.serialize(this);
  }
}

class User extends JsonSerializable {
  constructor(public name: string, public createdOn: Date) {
    super();
  }

  static fromSuperJSON(json: any) {
    return new User(json.name, json.createdOn);
  }

  toSuperJSON() {
    return { name: this.name, createdOn: this.createdOn };
  }
}

SuperJSON.registerSerializableClass(User);

const user = new User('user-123', new Date());

const superJsonstringifiedUser = SuperJSON.stringify(user);
// → {"json":{"name":"user-123","createdOn":"2026-03-16T01:36:57.217Z"},"meta":{"values":[["serializable-class","User"],{"createdOn":["Date"]}],"v":1}}

const superJsonrevivedUser = SuperJSON.parse(superJsonstringifiedUser);
// → User instance

const jsonStringifiedUser = JSON.stringify(user);
// → {"json":{"name":"user-123","createdOn":"2026-03-16T01:36:57.217Z"},"meta":{"values":[["serializable-class","User"],{"createdOn":["Date"]}],"v":1}}

const jsonRevivedUser = User.fromJSON(JSON.parse(jsonStringifiedUser));
// → User instance

---

Implementation notes

I already have a minimal, production-ready patch:

• New file: serializable-class-registry.ts (modeled exactly after class-registry.ts)
• New registerSerializableClass in index.ts.
• New serializable-class annotation + rule in transformer.ts (identical structure to classRule)
• One-line update in plainer.ts for deep traversal
• 5 new tests (works for serializable class, works for nested serializable class, constructor side-effects & initialization, external json props in serializable classes and throw if non-serializable class is passed to registerSerializableClass)

The change is purely additive, does not touch any existing behavior, and reuses all existing patterns, types, and error messages.

I will create the PR after this discussion 😄

---

Note

Initially toSuperJSON/fromSuperJSON were named toJSON/fromJSON, but to avoid any confusion with plain JSON serialization i renamed them and suggested pattern of using JsonSerializable in Example.

This allows full compatibility and safe serialization/deserialization even if plain JSON.stringify/JSON.parse are used but introduced two additional methods to our class, i would love to hear your opinion about naming and whether using toSuperJSON/fromSuperJSON is better or toJSON/fromJSON

[Skn0tt]

This seems only cosmetically different from registerCustom, am I missing something?

[ZiadTaha62]

I avoided using registerCustom for two reasons:

• First internally registerCustom uses isAplicable() to check passed value unlike registerClass that uses reference, so with every transform() we need to run isAplicable() of custom rules one by one (On), moreover transform() check composite rules first so with every transformed value even if primitive they will run. so if i need to register many classes (as in my case) it may cause performance overhead

• Secondly registerCustom was built so returned value should be native JSON value unlike registerClass that loops across allowedProps and transform them as well, so if class Admin returns class User and i passed it to registerCustom, class User will not be transformed even if registered

However i created a fork and updated earlier logic, registerSerializableClass can accept RegisterSerializableOptions with optional field methodNames to use already defined methods without enforcing any name (with fallback to default toSuperJSON/fromSuperJSON)

class User {
  constructor(public name: string) {}
  static deserialize(json: any) {
    return new User(json.name);
  }
  serialize() {
    return { name: this.name };
  }
}

SuperJSON.registerSerializableClass(User, {
  methodNames: { serialize: 'serialize', deserialize: 'deserialize' },
});

if we want to avoid hole additional registry what about adding optional methods or methodNames to registerClass options and use them if they are passed otherwise use original allowedProps behavior?

[ZiadTaha62]

Also i needed to updated plainer and transformer logic as well, transformer decides if transformed value isDeep and walker uses recursiveResult on transformed value that returns isDeep true or if object is plain object or array

updates in transformer logic:

export const transformValue = (
  value: any,
  superJson: SuperJSON
): { value: any; type: TypeAnnotation; isDeep: boolean } | undefined => {
  const applicableCompositeRule = findArr(compositeRules, rule =>
    rule.isApplicable(value, superJson)
  );
  if (applicableCompositeRule) {
    return {
      value: applicableCompositeRule.transform(value as never, superJson),
      type: applicableCompositeRule.annotation(value, superJson),
      isDeep: applicableCompositeRule.isDeep(value, superJson),
    };
  }

  const applicableSimpleRule = findArr(simpleRules, rule =>
    rule.isApplicable(value, superJson)
  );

  if (applicableSimpleRule) {
    return {
      value: applicableSimpleRule.transform(value as never, superJson),
      type: applicableSimpleRule.annotation,
      isDeep: applicableSimpleRule.isDeep,
    };
  }

  return;
};

updates in walker logic:

const isPlainObjectOrArray = (object: any) =>
  isPlainObject(object) || isArray(object);

export const walker = (
  object: any,
  identities: Map<any, any[][]>,
  superJson: SuperJSON,
  dedupe: boolean,
  path: any[] = [],
  objectsInThisPath: any[] = [],
  seenObjects = new Map<unknown, Result>(),
  isTransformation: boolean = false // Prevent overwrite of original object in identities map in recursive transformtion
): Result => {
  const primitive = isPrimitive(object);

  if (!primitive) {
    if (!isTransformation) addIdentity(object, path, identities);

    const seen = seenObjects.get(object);
    if (seen) {
      // short-circuit result if we've seen this object before
      return dedupe
        ? {
            transformedValue: null,
          }
        : seen;
    }
  }

  if (includes(objectsInThisPath, object)) {
    // prevent circular references
    return {
      transformedValue: null,
    };
  }

  // Try to tansform object (apply composite or simple rule if applicable)
  const transformationResult = transformValue(object, superJson);

  // Handle value if transformed
  if (transformationResult) {
    const { value, type, isDeep } = transformationResult;

    // If transformer mark value as non deep return it
    if (!isDeep) {
      const result: Result = {
        transformedValue: value,
        annotations: [type],
      };
      if (!primitive) seenObjects.set(object, result);
      return result;
    }

    // recurse if transformer mark value as deep
    const recursiveResult = walker(
      value,
      identities,
      superJson,
      dedupe,
      path,
      [...objectsInThisPath, object],
      seenObjects,
      true
    );

    const result: Result = recursiveResult.annotations
      ? {
          transformedValue: recursiveResult.transformedValue,
          annotations: [type, recursiveResult.annotations],
        }
      : {
          transformedValue: recursiveResult.transformedValue,
          annotations: [type],
        };

    if (!primitive) seenObjects.set(object, result);
    return result;
  }

  // Handle value if plain object or array
  if (isPlainObjectOrArray(object)) {
    const transformedValue: any = isArray(object) ? [] : {};
    const innerAnnotations: Record<string, Tree<TypeAnnotation>> = {};

    forEach(object, (value, index) => {
      if (
        index === '__proto__' ||
        index === 'constructor' ||
        index === 'prototype'
      ) {
        throw new Error(
          `Detected property ${index}. This is a prototype pollution risk, please remove it from your object.`
        );
      }

      const recursiveResult = walker(
        value,
        identities,
        superJson,
        dedupe,
        [...path, index],
        [...objectsInThisPath, object],
        seenObjects
      );

      transformedValue[index] = recursiveResult.transformedValue;

      if (isArray(recursiveResult.annotations)) {
        innerAnnotations[escapeKey(index)] = recursiveResult.annotations;
      } else if (isPlainObject(recursiveResult.annotations)) {
        forEach(recursiveResult.annotations, (tree, key) => {
          innerAnnotations[escapeKey(index) + '.' + key] = tree;
        });
      }
    });

    const result: Result = isEmptyObject(innerAnnotations)
      ? {
          transformedValue,
        }
      : {
          transformedValue,
          annotations: innerAnnotations,
        };

    if (!primitive) seenObjects.set(object, result);
    return result;
  }

  // Return value as is
  const result = {
    transformedValue: object,
  };
  if (!primitive) seenObjects.set(object, result);
  return result;
};

These are the main updates, i will make a PR request so you can see all changes