mutent-migration

library1.0.1jsnpmunverified

A plugin for Mutent (v6) that provides data versioning and migration strategies for entities managed by Mutent stores. Version 1.0.1 is current, stable. It allows defining migration functions per version, automatically applies them when fetching entities with older versions, and supports explicit version control. Released under MIT, maintained by the Mutent ecosystem author. Key differentiator: integrates seamlessly with Mutent's entity lifecycle, offering automatic upgrade/downgrade, error codes for invalid versions or missing strategies, and optional force update. Alternative to manual migration in data stores.

database

npm install mutent-migration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MUTENT-MIGRATION

mutent-migration

databasejavascriptv1.0.1

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.

migration

✓ import migration from 'mutent-migration'

✗ const migration = require('mutent-migration')

Default export. CJS require works but is not recommended for ESM projects.

Plugin

✓ import migration from 'mutent-migration'

✗ import { migration } from 'mutent-migration'

migration is the default export, not a named export. Use default import.

MutentError

✓ import { MutentError } from 'mutent'

✗ import { MutentError } from 'mutent-migration'

Error codes are throwed as MutentError instances from 'mutent', not from this plugin.

Creates a Mutent store with array adapter and migration plugin to automatically upgrade entities from version 0 to 1 by renaming a field.

import { Store } from 'mutent' import ArrayAdapter from 'mutent-array' import migration from 'mutent-migration' const items = [ { id: 1, oldFieldName: 'Calvin' } // implicit version 0 ] const store = new Store({ adapter: new ArrayAdapter({ items }), plugins: [ migration({ version: 1, key: 'v', strategies: { 1: ({ oldFieldName, ...data }) => ({ ...data, v: 1, newFieldname: oldFieldName }) } }) ] }) const result = await store.find(item => item.id === 1).unwrap() console.log(result) // { id: 1, v: 1, newFieldname: 'Calvin' } console.log(items[0]) // original not mutated, only in-memory copy

Debug

Known issues

gotchaMigration strategies only apply to fetched entities (find/findAll), not to created entities unless explicitVersion or forceUpdate is set.

fix

Use options.explicitVersion or options.forceUpdate if you need migration on create operations.

affects: >=1.0.0

gotchaThe original data source is not mutated; migration produces a new in-memory copy. Persistent storage requires custom adapter handling.

fix

After migration, you must explicitly call store.update() or adapter method to persist changes if needed.

affects: >=1.0.0

gotchaIf a strategy returns an entity with a version not matching the expected target version, EMUT_INVALID_UPGRADE error is thrown.

fix

Ensure migration functions set the version property to the strategy's key (target version).

affects: >=1.0.0

gotchaMissing strategies for required version upgrades cause EMUT_STRATEGY_EXPECTED error.

fix

Define all migration strategies for intermediate versions, not just the final target version.

affects: >=1.0.0

gotchaVersion key defaults to 'v', but can be customized via options.key. Ensure consistency across entities.

fix

If you change the key, all entities must use that key; otherwise EMUT_INVALID_ENTITY_VERSION error occurs.

affects: >=1.0.0

Errors

Common errors & fixes

MutentError [ERR_INVALID_ENTITY_VERSION]: The current Entity have an invalid version value.

Entity's version field is not a number or is missing incorrectly.

fix

Ensure the version field exists and is a valid number. For missing version, it is treated as 0.

MutentError [ERR_FUTURE_ENTITY]: Found an Entity that has a future version.

Entity version is greater than the target version specified in migration options.

fix

Check entity version and migration options.version. You may need to set version to a higher number or handle future entities.

MutentError [ERR_STRATEGY_EXPECTED]: An upgrade is required, but the required strategy function is missing.

No migration strategy defined for an intermediate version between entity current version and target version.

fix

Add strategies for all versions from entity current version+1 up to options.version.

MutentError [ERR_INVALID_UPGRADE]: A strategy was applied to an Entity, but the Entity does not contain the expected version.

Migration function returned an entity with version not matching the target version key.

fix

In the migration function, set the version field to the target version number (e.g., { v: 1, ... }).

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

mutentrequiredpeer dependency; provides Store and entity management framework

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/greguz/mutent-migration ↗

packagemutent-migration ↗

homepagehttps://github.com/greguz/mutent-migration#readme ↗