JSON Pilot
A library designed to help version JSON objects and migrate through them while also providing default data.
Features
-
Minimal Modification: Everything JSON Pilot needs to work is under
__pilot
to minimize potential collisions. - Plug'n play: Have an existing object? No problem! JSON Pilot will add it's necessary metadata and treat it as "version 0."
- Non-destructive: If a property already exist, JSON Pilot doesn't change it. It only changes what it needs to change.
- Automatic Sorting: Option to enable sorting of all properties in the object.
- CommonJS and ESM Support: JSONPilot leverages SWC to export the library in both CommonJS and ESM.
Getting Started
Installation
npm install jsonpilot
# or
yarn add jsonpilot
# or
pnpm add jsonpilot
Basic Usage
import { migrate, MigrateVersions } from 'jsonpilot'
const originalObject = {
some_value: '123',
}
const versions: MigrateVersions = [
{
version: 1,
migration: {
some_value: null,
},
},
{
version: 2,
migration: {
another_value: 0,
},
},
]
/**
* This will return the following object
* {
* some_value: '123',
* another_value: 0
* }
*/
const migratedObject = migrate(originalObject, versions)
API Reference
Migrate
migrate(source, versions, options)
-
source
: JSON object that is already defined and you want to migrate (if needed). -
versions
: An array of version definitions. The version number is not semantic versioning and follows a simple incremental pattern. -
options
: Optional options to use to further adjust the migration process.-
targetVersion
: If you want to override the default versioning process (to the latest). Defaults to-1
to always upgrade the object to the latest version available. -
sort
: Sorts the object (and nested objects) properties alphabetically. Defaults to false.
-
License
JSON Pilot is licensed under Mozilla Public License Version 2.0.
Support
While there's no official support, you can always create a new discussion or if you encounter a bug please feel free to open an issue