|
1 | 1 | # Upgrade Guide |
2 | 2 |
|
3 | | -This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [`CHANGELOG`][changelog]. |
| 3 | +This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [`CHANGELOG`](CHANGELOG.md). |
4 | 4 |
|
5 | | -## 6.0.0 |
| 5 | +## 1.0.0 |
6 | 6 |
|
7 | | -Legacy range options have been removed ([Level/community#86](https://github.com/Level/community/issues/86)). If you previously did: |
| 7 | +**Introducing `memory-level`: a fork of [`memdown`](https://github.com/Level/memdown) that removes the need for [`level-mem`](https://github.com/Level/mem), [`levelup`](https://github.com/Level/levelup) and more. It implements the [`abstract-level`](https://github.com/Level/abstract-level) interface instead of [`abstract-leveldown`](https://github.com/Level/abstract-leveldown) and thus has the same API as `level-mem` and `levelup` including encodings, promises and events. In addition, you can now choose to use Uint8Array instead of Buffer. Sublevels are builtin.** |
8 | 8 |
|
9 | | -```js |
10 | | -db.iterator({ start: 'a', end: 'z' }) |
11 | | -``` |
12 | | - |
13 | | -An error would now be thrown and you must instead do: |
14 | | - |
15 | | -```js |
16 | | -db.iterator({ gte: 'a', lte: 'z' }) |
17 | | -``` |
18 | | - |
19 | | -This release also drops support of legacy runtime environments ([Level/community#98](https://github.com/Level/community/issues/98)): |
20 | | - |
21 | | -- Node.js 6 and 8 |
22 | | -- Internet Explorer 11 |
23 | | -- Safari 9-11 |
24 | | -- Stock Android browser (AOSP). |
25 | | - |
26 | | -Lastly, and less likely to be a breaking change, the [`immediate`](https://github.com/calvinmetcalf/immediate) browser shim for `process.nextTick()` has been replaced with the smaller [`queue-microtask`](https://github.com/feross/queue-microtask). |
27 | | - |
28 | | -## 5.0.0 |
29 | | - |
30 | | -Support of keys & values other than strings and Buffers has been dropped. Internally `memdown` now stores keys & values as Buffers which solves a number of compatibility issues ([#186](https://github.com/Level/memdown/issues/186)). If you pass in a key or value that isn't a string or Buffer, it will be irreversibly stringified. |
31 | | - |
32 | | -## 4.0.0 |
33 | | - |
34 | | -This is an upgrade to `abstract-leveldown@6` which solves long-standing issues around serialization and type support. |
35 | | - |
36 | | -### Range options are now serialized |
37 | | - |
38 | | -Previously, range options like `lt` were passed through as-is by `abstract-leveldown`, unlike keys. This makes no difference for `memdown` as it does not serialize anything. |
39 | | - |
40 | | -### The rules for range options have been relaxed |
41 | | - |
42 | | -Because `null`, `undefined`, zero-length strings and zero-length buffers are significant types in encodings like `bytewise` and `charwise`, they became valid as range options in `abstract-leveldown`. This means `db.iterator({ gt: undefined })` is not the same as `db.iterator({})`. |
| 9 | +We've put together several upgrade guides for different modules. See the [FAQ](https://github.com/Level/community#faq) to find the best upgrade guide for you. This upgrade guide describes how to replace `memdown` or `level-mem` with `memory-level`. If you are using any of the following, please also read the upgrade guide of [`abstract-level@1`](https://github.com/Level/abstract-level/blob/main/UPGRADING.md#100) which goes into more detail about these: |
43 | 10 |
|
44 | | -For `memdown`, when used by itself, the behavior of `null`, `undefined`, zero-length strings and zero-length buffers is undefined. |
| 11 | +- Specific error messages (replaced with error codes) |
| 12 | +- The callback argument of the constructor (gone) |
| 13 | +- The `'binary'` encoding (renamed to `'buffer'`, with `'binary'` as an alias) |
| 14 | +- The `db.iterator().end()` method (renamed to `close()`, with `end()` as an alias) |
| 15 | +- Zero-length keys and range options (now valid) |
| 16 | +- The `'ascii'`, `'ucs2'`, `'utf16le'` and `'id'` encodings (gone) |
| 17 | +- The undocumented `encoding` alias for the `valueEncoding` option (gone) |
| 18 | +- The `db.supports.bufferKeys` property. |
45 | 19 |
|
46 | | -### Nullish values are rejected |
| 20 | +Support of Node.js 10 has been dropped. |
47 | 21 |
|
48 | | -In addition to rejecting `null` and `undefined` as _keys_, `abstract-leveldown` now also rejects these types as _values_, due to preexisting significance in streams and iterators. |
| 22 | +### Upgrade from `level-mem` to `memory-level` |
49 | 23 |
|
50 | | -### Zero-length array keys are rejected |
| 24 | +Using `new` is now required. If you previously did: |
51 | 25 |
|
52 | | -Though this was already the case, `abstract-leveldown` has replaced the behavior with an explicit `Array.isArray()` check and a new error message. |
53 | | - |
54 | | -### Browser support |
55 | | - |
56 | | -IE10 has been dropped. |
| 26 | +```js |
| 27 | +const mem = require('level-mem') |
| 28 | +const db1 = mem() |
| 29 | +const db2 = mem({ valueEncoding: 'json' }) |
| 30 | +``` |
57 | 31 |
|
58 | | -## 3.0.0 |
| 32 | +You must now do: |
59 | 33 |
|
60 | | -Dropped support for node 4. No other breaking changes. |
| 34 | +```js |
| 35 | +const { MemoryLevel } = require('memory-level') |
| 36 | +const db1 = new MemoryLevel() |
| 37 | +const db2 = new MemoryLevel({ valueEncoding: 'json' }) |
| 38 | +``` |
61 | 39 |
|
62 | | -## 2.0.0 |
| 40 | +Node.js readable streams must now be created with a new standalone module called [`level-read-stream`](https://github.com/Level/read-stream), rather than database methods like `db.createReadStream()`. Please see its [upgrade guide](https://github.com/Level/read-stream/blob/main/UPGRADING.md#100) for details. |
63 | 41 |
|
64 | | -This release drops Node.js 0.12, brings `memdown` up to par with latest [`levelup`][levelup] (v2) and [`abstract-leveldown`][abstract-leveldown] (v4), simplifies serialization and removes global state. |
| 42 | +### Upgrade from `memdown` to `memory-level` |
65 | 43 |
|
66 | | -### Targets latest [`levelup`][levelup] |
| 44 | +_This section is only relevant if you're using `memdown` directly, rather than as a transitive dependency of `level-mem`._ |
67 | 45 |
|
68 | | -Usage has changed to: |
| 46 | +The `asBuffer`, `valueAsBuffer` and `keyAsBuffer` options have been replaced with encoding options. The default encoding is `'utf8'` which means operations return strings rather than Buffers by default. If you previously did: |
69 | 47 |
|
70 | 48 | ```js |
71 | | -const levelup = require('levelup') |
72 | 49 | const memdown = require('memdown') |
| 50 | +const db = memdown() |
73 | 51 |
|
74 | | -const db = levelup(memdown()) |
| 52 | +db.get('example', { asBuffer: false }, callback) |
| 53 | +db.get('example', callback) |
75 | 54 | ``` |
76 | 55 |
|
77 | | -From the old: |
| 56 | +You must now do: |
78 | 57 |
|
79 | 58 | ```js |
80 | | -const db = levelup('mydb', { db: memdown }) |
81 | | -``` |
| 59 | +const { MemoryLevel } = require('memory-level') |
| 60 | +const db = new MemoryLevel() |
82 | 61 |
|
83 | | -### No stringification of keys and values |
| 62 | +db.get('example', callback) |
| 63 | +db.get('example', { valueEncoding: 'buffer' }, callback) |
| 64 | +``` |
84 | 65 |
|
85 | | -This means that in addition to Buffers, you can store any JS type without the need for [`encoding-down`][encoding-down]. This release also makes behavior consistent in Node.js and browsers. Please refer to the [README](./README.md) for a detailed explanation. |
| 66 | +Or using promises (new): |
86 | 67 |
|
87 | | -### No global state or `location` argument |
| 68 | +```js |
| 69 | +const str = await db.get('example') |
| 70 | +const buf = await db.get('example', { valueEncoding: 'buffer' }) |
| 71 | +``` |
88 | 72 |
|
89 | | -If you previously did this to make a global store: |
| 73 | +Or using Uint8Array (new): |
90 | 74 |
|
91 | 75 | ```js |
92 | | -const db = levelup('mydb', { db: memdown }) |
| 76 | +const arr = await db.get('example', { valueEncoding: 'view' }) |
93 | 77 | ``` |
94 | 78 |
|
95 | | -You must now attach the store to a global yourself (if you desire global state): |
| 79 | +If you were wrapping `memdown` with `levelup`, `encoding-down` and / or `subleveldown`, remove those modules. If you previously did: |
96 | 80 |
|
97 | 81 | ```js |
98 | | -const db = window.mydb = levelup(memdown()) |
99 | | -``` |
| 82 | +const memdown = require('memdown') |
| 83 | +const levelup = require('levelup') |
| 84 | +const enc = require('encoding-down') |
| 85 | +const subleveldown = require('subleveldown') |
100 | 86 |
|
101 | | -### No `null` batch operations |
| 87 | +const db = levelup(enc(memdown())) |
| 88 | +const sublevel = subleveldown(db, 'foo') |
| 89 | +``` |
102 | 90 |
|
103 | | -Instead of skipping `null` operations, `db.batch([null])` will throw an error courtesy of [`abstract-leveldown`][abstract-leveldown]. |
| 91 | +You must now do: |
104 | 92 |
|
105 | | -[changelog]: CHANGELOG.md |
| 93 | +```js |
| 94 | +const { MemoryLevel } = require('memory-level') |
| 95 | +const db = new MemoryLevel() |
| 96 | +const sublevel = db.sublevel('foo') |
| 97 | +``` |
106 | 98 |
|
107 | | -[abstract-leveldown]: https://github.com/Level/abstract-leveldown |
| 99 | +Lastly, private properties like `_store` (unlikely used externally) are no longer accessible. |
108 | 100 |
|
109 | | -[levelup]: https://github.com/Level/levelup |
| 101 | +--- |
110 | 102 |
|
111 | | -[encoding-down]: https://github.com/Level/encoding-down |
| 103 | +_For earlier releases, before `memory-level` was forked from `memdown`, please see [the upgrade guide of `memdown`](https://github.com/Level/memdown/blob/master/UPGRADING.md)._ |
0 commit comments