ts-jackson

Map ugly API JSON into clean TypeScript classes — and back. Inspired by Java's Jackson, built for the shape of real-world APIs.

import { JsonProperty, Serializable, deserialize, serialize } from 'ts-jackson'

const response = {
  track: {
    id: '42',
    album: { images: [{ url: 'https://cover.jpg' }] },
    duration_ms: 235000,
  },
}

@Serializable()
class Track {
  @JsonProperty('track.id')
  id: string

  @JsonProperty('track.album.images[0].url')
  coverUrl: string

  @JsonProperty('track.duration_ms')
  durationMs: number
}

const track = deserialize(response, Track)
// Track { id: '42', coverUrl: 'https://cover.jpg', durationMs: 235000 }

serialize(track)
// restores the original nested shape

Why ts-jackson

• Deep path mapping — properties resolve through lodash path patterns ('track.album.images[0].url'), so a flat domain class can be built from arbitrarily nested JSON and serialized back to the same shape. Flat-rename-only mappers can't restructure.
• Works with both decorator standards — legacy experimentalDecorators and TC39 standard decorators (the TypeScript 5+ default). That includes toolchains without emitDecoratorMetadata support such as esbuild and Vite.
• Safe, zod-style parsing — safeDeserialize returns { success, data | errors } and collects every property error in one pass instead of throwing on the first.
• Typed, structured errors — every error carries a kind discriminant plus fields like propertyName, path, expected, and the offending value.
• Strict mode, polymorphism, Maps/dictionaries, naming strategies, access control — see the tour below.

Installation

npm install ts-jackson reflect-metadata

reflect-metadata is a peer dependency; the library imports it internally, so no extra setup is needed in your code.

TypeScript configuration

Legacy decorators (full feature set including type inference):

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Standard (TC39) decorators — no flags at all. Types cannot be inferred (the standard has no emitDecoratorMetadata equivalent), so pass them explicitly where conversion matters:

@Serializable()
class Event {
  @JsonProperty({ type: Date })
  startsAt: Date

  @JsonProperty({ elementType: Image }) // elementType implies an array
  images: Image[]

  @JsonProperty({ type: Map, elementType: Image })
  imagesBySize: Map<string, Image>
}

Everything else — paths, hooks, strict, required, polymorphism — behaves identically in both modes.

API tour

Entry points

deserialize(json, Track)                 // throws on the first error
serialize(track)

deserializeArray(jsonArray, Track)       // top-level JSON arrays
serializeArray(tracks)

safeDeserialize(json, Track)             // never throws, collects all errors
safeSerialize(track)
safeDeserializeArray(jsonArray, Track)

deserialize forwards extra arguments to the constructor:

@Serializable()
class Cat {
  @JsonProperty() name: string
  constructor(readonly owner: string) {}
}

deserialize({ name: 'Moon' }, Cat, 'Ilias')

@JsonProperty

Accepts a path string, an array of paths, or an options object:

| Option | Purpose | | --- | --- | | path | JSON path (lodash syntax); defaults to the property name | | paths | Multiple paths resolved into a tuple/array | | pathAlternatives | Deserialize-only aliases; first non-null wins, primary path is tried first | | required | Throw RequiredPropertyError when the value is missing | | default | Substitute for missing values (checked before required, so the two combine) | | strict | Reject JSON values whose type doesn't match — see Strict mode | | access | 'deserialize-only' (skip on serialize) or 'serialize-only' (skip on deserialize) | | type | Explicit type; accepts a class or a lazy arrow thunk () => Class | | elementType | Element type for Array/Set/Map/dictionary values; thunk allowed | | resolveType | (json) => Class — per-value polymorphic dispatch | | validate | Predicate; failure throws ValidatePropertyError | | beforeDeserialize / deserialize / afterDeserialize | Deserialization hooks | | beforeSerialize / serialize / afterSerialize | Serialization hooks |

Deserialization pipeline order: resolve value → default → required → beforeDeserialize → strict → deserialize (custom or built-in) → validate → assign; afterDeserialize hooks run after the whole instance is populated.

@Serializable

import { camelToSnakeCase } from 'ts-jackson'

@Serializable({
  formatPropertyName: camelToSnakeCase, // accessToken ⇆ access_token
  strict: true,                         // strict for every property
})
class Token {
  @JsonProperty() accessToken: string   // maps to 'access_token'
  @JsonProperty('expires') expiresIn: number // explicit path wins
  @JsonProperty({ strict: false }) raw: unknown // per-property opt-out
}

Both options are inherited by subclasses and can be overridden. Bundled naming strategies: camelToSnakeCase, camelToKebabCase, camelToPascalCase — or pass any (name: string) => string.

Path resolution

// Single deep path
@JsonProperty('track.album.images[0].url')
coverUrl: string

// Multiple paths → tuple
@JsonProperty({ paths: ['id', 'meta.rev'] })
idAndRevision: [string, number]

// Aliases: first non-null of snack → treat → goodie
@JsonProperty({ pathAlternatives: ['treat', 'goodie'] })
snack: string

Serialization always writes to the primary path, so deserialize(serialize(x)) is stable.

Collections

Array, Set, Map, and plain-object dictionaries are supported; elementType types their values:

@Serializable()
class Gallery {
  @JsonProperty({ elementType: Image })
  images: Image[]

  @JsonProperty({ elementType: Image })
  imagesBySize: Map<string, Image>        // { small: {...} } → Map

  @JsonProperty({ elementType: Image })
  imagesByName: Record<string, Image>     // values become Image instances
}

Polymorphism

resolveType picks the concrete class per value:

@Serializable()
class Canvas {
  @JsonProperty({
    elementType: Shape,
    resolveType: (json) => ('radius' in json ? Circle : Square),
  })
  shapes: Shape[]
}

Serialization dispatches on each value's runtime class automatically.

Self-referencing and circular types

Use arrow-function thunks when a class references itself or when model files import each other circularly:

@Serializable()
class Category {
  @JsonProperty() name: string

  @JsonProperty({ elementType: () => Category })
  children: Category[]
}

Strict mode

By default, primitives are coerced (Number('42') → 42, Number('abc') → NaN). With strict — per property or class-wide — the raw JSON value must already match the declared type:

@JsonProperty({ strict: true })
age: number

deserialize({ age: '30' }, Person)
// TypeMismatchError: Property 'age' (path: 'age') in Person failed type
// check: expected Number, received string ("30").

null and missing values pass strict checks (use required for presence); a custom deserialize function bypasses them.

Error handling

All library errors extend TsJacksonError and expose structured fields:

| Class | kind | Fields | | --- | --- | --- | | RequiredPropertyError | 'required' | propertyName, path, className | | TypeMismatchError | 'type-mismatch' | propertyName, path, className, expected, value | | ValidatePropertyError | 'validation' | propertyName, className, value | | SerializableError | 'not-serializable' | className |

Throwing style:

try {
  deserialize(json, Track)
} catch (error) {
  if (error instanceof TypeMismatchError) {
    console.log(error.propertyName, error.expected, error.value)
  }
}

Functional style — collects every error in one pass:

import { safeDeserialize, isTsJacksonError } from 'ts-jackson'

const result = safeDeserialize(json, Track)
if (!result.success) {
  for (const error of result.errors.filter(isTsJacksonError)) {
    switch (error.kind) {
      case 'required':      // error.path
      case 'type-mismatch': // error.expected, error.value
      case 'validation':    // error.value
    }
  }
}

SerializableEntity

Base class bundling the API and removing the need for @Serializable:

class Image extends SerializableEntity {
  @JsonProperty({ required: true })
  url: string
}

const image = Image.deserialize({ url: '...' })
image.serialize()
image.stringify()

Migrating from v1

• Node/TS baseline: compiled output targets ES2017; TypeScript peer tooling expects modern versions.
• reflect-metadata is now a peer dependency — installed alongside the lib (npm 7+ does this automatically); the library still imports it for you.
• Errors: collection shape mismatches now throw TypeMismatchError (previously a bare TypeError); all errors expose structured fields and kind.
• Packaging: an exports map now defines the public entry point — deep imports from dist/ internals are no longer part of the API. Plain Node ESM (import ... from 'ts-jackson') now works.
• Everything decorated for v1 keeps deserializing identically; subclass metadata no longer leaks into parent classes (previously a bug).

Examples

See src/examples for real-world models (Spotify API entities, OAuth tokens) used as living documentation and tests.

License

MIT