rs-migrate

library1.0.2jsnpmunverified

Versioned document migration library for remoteStorage apps. v1.0.2 (2024). No dependencies. Documents track their own version via a configurable field (default `_migrateVersion`). When reading a document, `migrateDocument` deep-clones it and runs registered transforms in order if behind. `migrateAll` batch-migrates full collections via an adapter. Distinguishes itself from generic migration tools by being purpose-built for remoteStorage's document model (zero deps, lazy on read, eager batch optional). Ships TypeScript definitions.

storage

npm install rs-migrate

package ↗

INSTALL

IMPORT

SIG · RS-MIGRATE

rs-migrate

storagejavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMigrator

✓ import { createMigrator } from 'rs-migrate'

✗ import createMigrator from 'rs-migrate'

Named export only. No default export.

Migrator

✓ import type { Migrator } from 'rs-migrate'

Type import for TypeScript. The return type of createMigrator.

MigrationDescriptor

✓ import type { MigrationDescriptor } from 'rs-migrate'

Type for the migration object passed to register().

Demonstrates creating a migrator, registering two migrations on the 'contacts' collection, and migrating a document from version 0 to 2.

import { createMigrator } from 'rs-migrate'; const migrator = createMigrator(); migrator.register({ version: 1, collection: 'contacts', description: 'Split full name into first/last', transform(doc) { if (doc.name && !doc.firstName) { const [first, ...rest] = doc.name.split(' '); doc.firstName = first; doc.lastName = rest.join(' '); delete doc.name; } return doc; }, }); migrator.register({ version: 2, collection: 'contacts', description: 'Add default country', transform(doc) { doc.country = doc.country ?? 'US'; return doc; }, }); const rawContact = { _migrateVersion: 0, name: 'John Doe' }; const contact = migrator.migrateDocument('contacts', rawContact); // contact._migrateVersion === 2 // contact.firstName === 'John', contact.lastName === 'Doe', contact.country === 'US'

Debug

Known issues

gotchaThe default version field is '_migrateVersion'. If your document has a different version property, you must pass `versionField` to `createMigrator`.

fix

Use `createMigrator({ versionField: 'customVersion' })` to match your existing schema.

affects: >=1.0.0

gotcha`migrateDocument` deep-clones the document before transforms. Mutations inside transforms are safe but be aware that the original reference is not mutated unless the document was already at the latest version (then passed through unchanged).

fix

If you need to modify the original, assign the result back: `doc = migrator.migrateDocument('contacts', doc)`.

affects: >=1.0.0

gotchaDocuments without a version field are treated as version 0. If your documents have a version field with value undefined/null, they will also be treated as version 0.

fix

Ensure documents have the version field set explicitly to avoid unexpected migration.

affects: >=1.0.0

gotchaRegistering a migration with a version that already exists for the same collection throws an error. No overwriting allowed.

fix

Use a new version number (highest existing + 1) or use `registerAll` which is atomic.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'rs-migrate' or its corresponding type declarations.

The package may not be installed or TypeScript cannot find its typings.

fix

Run `npm install rs-migrate` and ensure `tsconfig.json` includes `"node_modules/@types"` or the module is in `node_modules`.

TypeError: migrator.register is not a function

`createMigrator` returns a migrator instance with `register`, but maybe you imported incorrectly (e.g., default import).

fix

Use `import { createMigrator } from 'rs-migrate'` instead of default import.

Error: Migration version must be a positive integer.

You passed a non-positive integer (e.g., 0, -1) or non-integer (e.g., 1.5) as the version in a migration descriptor.

fix

Ensure version is a positive integer (>=1).

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagers-migrate ↗