{"_id":"@davestewart/extension-migrations","_rev":"1-6b2623b488be9a64c473128b69070c4a","name":"@davestewart/extension-migrations","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@davestewart/extension-migrations","version":"1.0.0","keywords":["migrations","web","extensions"],"author":{"name":"Dave Stewart"},"license":"MIT","_id":"@davestewart/extension-migrations@1.0.0","maintainers":[{"name":"davestewart","email":"dev@davestewart.co.uk"}],"homepage":"https://github.com/davestewart/v#readme","bugs":{"url":"https://github.com/davestewart/v/issues"},"dist":{"shasum":"c28d56c2a91537c7b2ae37ba4cd97bf4765f60e3","tarball":"https://registry.npmjs.org/@davestewart/extension-migrations/-/extension-migrations-1.0.0.tgz","fileCount":4,"integrity":"sha512-rG4UfDgmoD4Hdm5bED18jblYCo2AFJEkrW4oJsZfyO/Crg6zs/Do7jx57SRjsPr4s9rZg2KSQVbXhUoQNQ8EYw==","signatures":[{"sig":"MEUCIQDECFfKyJ9gp8/TvcGSAU0ky6hHHBYwxpCt1wp9xQ3llQIgVJFDxO/oDD4USb8ZSCer3VI0FDpkAe9nXUkX9y5THFQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9434},"main":"migrate.js","type":"module","gitHead":"5808649edf6a7699572954ef259bc2cd0318b458","scripts":{"test":"vitest"},"_npmUser":{"name":"davestewart","email":"dev@davestewart.co.uk"},"repository":{"url":"git+https://github.com/davestewart/v.git","type":"git"},"_npmVersion":"10.7.0","description":"Simple migration tool for browser extensions","directories":{},"_nodeVersion":"20.15.1","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.5"},"_npmOperationalInternal":{"tmp":"tmp/extension-migrations_1.0.0_1739899030094_0.5352626530707532","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@davestewart/extension-migrations","version":"1.0.1","description":"Simple migration tool for browser extensions","author":{"name":"Dave Stewart"},"license":"MIT","main":"migrate.js","type":"module","scripts":{"test":"vitest"},"devDependencies":{"vitest":"^3.0.5"},"homepage":"https://github.com/davestewart/extension-migrations#readme","repository":{"type":"git","url":"git+https://github.com/davestewart/extension-migrations.git"},"keywords":["migrations","web","extensions"],"bugs":{"url":"https://github.com/davestewart/extension-migrations/issues"},"_id":"@davestewart/extension-migrations@1.0.1","gitHead":"7725fc567849311628f6100c34c1a236597bedbe","_nodeVersion":"20.15.1","_npmVersion":"10.7.0","dist":{"integrity":"sha512-GMDGw1gIsaGjFK7X5RWMuU2nwpy31m823Ph/W0LLQaizj8XpTDHVWDwK7smUTJ3R59/xX56A7492Tkl2qcp2Ew==","shasum":"060bf9d018cf2fa3fac298be0019d1e5bf35e1da","tarball":"https://registry.npmjs.org/@davestewart/extension-migrations/-/extension-migrations-1.0.1.tgz","fileCount":4,"unpackedSize":9491,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCukBK801UV/jWnqkkCew6dRpl6MnfXYpyog+A6tIpIugIgO30Mr7Md6Jg/7a4tuAPxHPGEYC1kiM/L4RnPhwgd600="}]},"_npmUser":{"name":"davestewart","email":"dev@davestewart.co.uk"},"directories":{},"maintainers":[{"name":"davestewart","email":"dev@davestewart.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/extension-migrations_1.0.1_1739899760913_0.3586932266204952"},"_hasShrinkwrap":false}},"time":{"created":"2025-02-18T17:17:10.025Z","modified":"2025-02-18T17:29:21.226Z","1.0.0":"2025-02-18T17:17:10.261Z","1.0.1":"2025-02-18T17:29:21.076Z"},"bugs":{"url":"https://github.com/davestewart/extension-migrations/issues"},"author":{"name":"Dave Stewart"},"license":"MIT","homepage":"https://github.com/davestewart/extension-migrations#readme","keywords":["migrations","web","extensions"],"repository":{"type":"git","url":"git+https://github.com/davestewart/extension-migrations.git"},"description":"Simple migration tool for browser extensions","maintainers":[{"name":"davestewart","email":"dev@davestewart.co.uk"}],"readme":"# Extension Migrations\n\n> Simple migration tool for browser extensions\n\n## Overview\n\nExtension Migrations is a simple library designed to run migrations in browser extensions when the version is changed.\n\nUse cases might be:\n\n- modifying storage key format\n- preparing new data\n- deleting old data\n\n## Installation\n\nThe library supports two installation methods.\n\n### Copy and paste\n\nThe file in `migrations.js` is standalone JavaScript with JSDoc types.\n\nIf your project is small, and missing a compile step, just copy the file or the code and import.\n\n### NPM\n\nInstall from NPM like any other package:\n\n```\nnpm i @davestewart/extension-migrations\n```\n\n## Usage\n\n### Setup\n\nMigrations should be modelled as a hash of `version: migration` pairs, each with `up` and `down` methods:\n\n```js\nconst migrations = {\n  '0.1': {\n    up () {\n      // one time setup\n    }\n  },\n\n  '0.5': {\n    up () {\n      // do some action\n    },\n    down () {\n      // undo some action\n    },\n  }\n}\n```\n\nThe `up` methods are called when a higher version is installed, and `down` migrations when a lower version is installed. \n\nNote that migration keys must **exactly** match the version strings in your extension's manifest, i.e. `2.0` is different from `2.0.0`.\n\n### Running migrations\n\nTo run a migration, import and call the `migrate()` function:\n\n```js\nimport { migrate } from '@davestewart/extension-migrations'\n\nconst result = await migrate({ ... }, fromVersion, toVersion)\n```\n\nYou should run the migration in the `onInstalled` listener: \n\n```js\nchrome.runtime.onInstalled.addListener(async (event) => {\n  // variables\n  const { version } = chrome.runtime.getManifest()\n  const { previousVersion } = event\n  \n  // run migrations\n  const { type, versions } = await migrate(migrations, previousVersion, version)\n  \n  // log\n  console.log('migration complete:', type, versions)\n})\n```\n\nNote that:\n\n- migrations will run only when the extension's version changes\n- on extension reload, no migrations will run, as the version has not changed\n- to downgrade an extension in development, change the manifest version, then reload the extension\n\nThe function returns the following data:\n\n```js\n{\n  versions: ['1.0', '1.1', ...],\n  type: 'all',\n}\n```\n\nThe `versions` property will be an array of the versions that were run.\n\nThe `type` property will be one of:\n\n- `skip`: there were no migrations to run\n- `all`:  the extension was installed\n- `none`: the extension was reloaded\n- `up`: the extension was upgraded \n- `down`: the extension was downgraded (likely only in development)\n\n## Error handling\n\nTo handle errors, wrap the migration in a `try/catch`:\n\n```js\n// migrations\nconst migrations = {\n  '2.0': {\n    up (version) {\n      errVersion = version\n      throw new Error('Could not create database')\n    },\n    down () {}\n  },\n}\n\n// track errors\nlet errVersion\n\n// run migrations\ntry {\n  await migrate(migrations, previousVersion, version)\n}\ncatch (err) {\n  console.log(`${err.message} for version ${errVersion}`)\n}\n```\n","readmeFilename":"README.md"}