JSOG for TypeScript

Common errors

• ReferenceError: Reflect is not defined

  cause The `reflect-metadata` polyfill is missing or not imported at the application's entry point, which is crucial for TypeScript decorators to emit and retrieve type metadata at runtime.
  fix Run `npm install reflect-metadata` and add `import 'reflect-metadata';` as the very first line in your main application entry file (e.g., `main.ts`).

• Error: Cannot convert object with JSOG ID to class. [class name] expected.

  cause During `deserializeObject` or `deserializeArray`, `jsog-typescript` failed to instantiate the target TypeScript class, often because of missing decorators or incorrect `tsconfig.json` settings.
  fix Verify that `experimentalDecorators` and `emitDecoratorMetadata` are enabled in `tsconfig.json` and that all properties intended for deserialization into custom types have the `@JsonProperty()` decorator, with type arguments where necessary (e.g., `@JsonProperty(MyClass)`).

• Property 'someMethod' does not exist on type 'MyClass' after deserialization.

  cause While the object might look correct, it was likely deserialized as a plain JavaScript object or an incorrect type, meaning methods defined on your TypeScript class are not available.
  fix Ensure you are using `jsog.deserializeObject(data, MyClass)` or `jsog.deserializeArray(data, MyClass)` to explicitly tell `jsog-typescript` to instantiate objects as `MyClass` instances, and that `reflect-metadata` is properly imported.

Warnings

• breaking Enabling TypeScript's `experimentalDecorators` and `emitDecoratorMetadata` compiler options is mandatory for this library to function correctly at compile time.
  Fix: Add `"experimentalDecorators": true, "emitDecoratorMetadata": true` to the `compilerOptions` section of your `tsconfig.json`.
• breaking The `reflect-metadata` package is a required runtime dependency for `emitDecoratorMetadata` to provide type information at runtime. Without it, deserialization into specific TypeScript classes will fail silently or with runtime errors.
  Fix: Install `reflect-metadata` (`npm install reflect-metadata`) and add `import 'reflect-metadata';` at the very top of your application's main entry point (e.g., `main.ts` or `index.ts`).
• gotcha For complex nested objects or arrays of custom types, the `@JsonProperty` decorator requires a type argument to correctly instantiate objects during deserialization.
  Fix: For properties that are a single custom object, use `@JsonProperty(MyClass)`. For properties that are arrays of custom objects, use `@JsonProperty(MyClass)` on the array property itself.
• gotcha When deserializing to a specific TypeScript class, ensure that the class has a default (no-argument) constructor, or that the library can infer how to instantiate it. Missing default constructors can lead to errors.
  Fix: If your class requires constructor arguments, consider providing a default constructor or ensuring your class design allows for no-argument instantiation when deserialized by `jsog-typescript`.

Install

• npm install jsog-typescript npm
• yarn add jsog-typescript yarn
• pnpm add jsog-typescript pnpm

Imports

• jsogService
  wrong:

  const jsogService = require('jsog-typescript').jsogService;

  correct:

  import { jsogService } from 'jsog-typescript'

  This is a pre-instantiated singleton service suitable for most basic serialization and deserialization tasks.
• JsogService
  wrong:

  import JsogService from 'jsog-typescript';

  correct:

  import { JsogService } from 'jsog-typescript'

  Import the class directly to create new instances, for example, when integrating into dependency injection frameworks like Angular or for custom configurations.
• JsonProperty
  wrong:

  import { JsonProperty } from 'jsog-typescript/decorators';

  correct:

  import { JsonProperty } from 'jsog-typescript'

  The `@JsonProperty()` decorator is crucial for enabling type-aware deserialization, mapping JSON properties to TypeScript class properties. It can also accept a class type for properties that are arrays of custom objects.

Quickstart

This quickstart demonstrates defining TypeScript classes with `@JsonProperty` decorators, serializing an object graph including circular references, and then deserializing it back into full TypeScript class instances, preserving methods and `instanceof` checks.

import { jsogService, JsonProperty, JsogService } from 'jsog-typescript';
import 'reflect-metadata'; // Essential for decorators to work at runtime

// 1. Define a TypeScript class with decorators
class Address {
  @JsonProperty() street: string = '';
  @JsonProperty() city: string = '';

  getFullAddress(): string {
    return `${this.street}, ${this.city}`;
  }
}

class Person {
  @JsonProperty() id: number = 0;
  @JsonProperty() name: string = '';
  @JsonProperty(Address) address: Address | undefined;
  @JsonProperty(Person) friends: Person[] = []; // Array of nested custom objects

  greet(): string {
    return `Hello, my name is ${this.name}!`;
  }
}

// 2. Instantiate and serialize an object graph
const person1 = new Person();
person1.id = 1;
person1.name = 'Alice';
person1.address = new Address();
person1.address.street = '123 Main St';
person1.address.city = 'Anytown';

const person2 = new Person();
person2.id = 2;
person2.name = 'Bob';
person2.friends.push(person1); // Create a circular reference

person1.friends.push(person2);

const serializedGraph = jsogService.serialize(person1);
console.log('Serialized Graph:', JSON.stringify(serializedGraph, null, 2));

// 3. Deserialize back into TypeScript objects
const deserializedPerson = jsogService.deserializeObject(serializedGraph, Person);

console.log('\nDeserialized Person:', deserializedPerson);
console.log('Is instance of Person:', deserializedPerson instanceof Person); // true
console.log('Is instance of Address:', deserializedPerson.address instanceof Address); // true
console.log('Person greeting:', deserializedPerson.greet());
console.log('Person address:', deserializedPerson.address?.getFullAddress());
console.log('Friend greeting:', deserializedPerson.friends[0]?.greet());