Add addEarlyCallback method whose callbacks, unlike the later-executed addCallback ones, can themselves use idb-schema methods (e.g., to convert from JSON to idb-schema) though, since they execute within upgradeneeded cannot support Promises (as can the callbacks within addCallback when schema.open or schema.upgrade are used); document

Author: brettz9

History.md

@@ -4,6 +4,8 @@
   which can support promises returned by `addCallback` callbacks (and a
   `flushIncomplete` method for flushing storage pertaining to incomplete
   upgrades)
+* Feature: Add `addEarlyCallback` to allow use of `idb-schema` methods
+  within these synchronous callbacks
 
 ## 3.2.1 / 2015-11-29
 

Readme.md

@@ -90,7 +90,8 @@ schema.open('myDb', 3).then((db) => {
 However, unlike `callback()`, when `schema.open` is used, the callbacks
 added by `addCallback` cannot handle operations such as adding stores
 or indexes (though these operations can be executed with the other
-methods of idb-schema anyways).
+methods of idb-schema anyways) though those added by `addEarlyCallback`
+can be.
 
 Besides conducting an upgrade, `schema.open` uses the `open` of
 [idb-factory](https://github.com/treojs/idb-factory) behind the scenes, so
@@ -223,6 +224,26 @@ Options:
 
 Delete index by `name` from current store.
 
+### schema.addEarlyCallback(cb)
+
+Adds a `cb` to be executed at the beginning of the `upgradeneeded` event
+and passed the event object. This will, out of necessity, run synchronously,
+so promises cannot safely be used therein (whether used in `schema.callback`
+or `schema.open`/`schema.upgrade`).
+
+However, due to their early execution, such callbacks are, unlike
+`addCallback` callbacks used with `schema.open`/`schema.upgrade`,
+able to use methods such as `addStore`.
+
+```js
+const schema = new Schema()
+.addStore('users', { increment: true, keyPath: 'id' })
+.addIndex('byName', 'name')
+.addEarlyCallback((e) => {
+  schema.addIndex('byId', 'id')
+})
+```
+
 ### schema.addCallback(cb)
 
 Adds a `cb` to be executed at the end of the `upgradeneeded` event
@@ -249,7 +270,8 @@ these methods, unlike `schema.callback`, will cause the callbacks
 to be executed safely within the more persistent `onsuccess` event (and the
 callback will be passed the database result instead of the `upgradeneeded`
 event). If you do not need promises, you will have the option of using
-`schema.callback` in addition to `schema.open` or `schema.upgrade`.
+`schema.callback` in addition to `schema.open` or `schema.upgrade` (or
+you can use `addEarlyCallback`).
 
 ### schema.clone()
 

src/index.js

@@ -52,6 +52,7 @@ export default class Schema {
       indexes: [],      // store.createIndex
       dropIndexes: [],  // store.deleteIndex
       callbacks: [],
+      earlyCallbacks: [],
       version: version, // version
     }
 
@@ -178,6 +179,11 @@ export default class Schema {
     return this
   }
 
+  addEarlyCallback(cb) {
+    this._versions[this.version()].earlyCallbacks.push(cb)
+    return this
+  }
+
   /**
    * Flushes storage pertaining to incomplete upgrades
    *
@@ -232,7 +238,7 @@ export default class Schema {
       dbLast.close()
 
       setTimeout(() => {
-        open(dbName, versionSchema.version, upgradeneeded((e, ...dbInfo) => {
+        open(dbName, versionSchema.version, upgradeneeded((...dbInfo) => {
           upgradeVersion(versionSchema, ...dbInfo)
         })).then((db) => {
           afterOpen(db, res, rej, start)
@@ -342,7 +348,7 @@ export default class Schema {
         reject(err)
         return
       }
-      const upgrade = upgradeneeded((e, ...dbInfo) => {
+      const upgrade = upgradeneeded((...dbInfo) => {
         // Upgrade from 0 to version 1
         const versionIter = versions.next()
         if (versionIter.done) {
@@ -379,10 +385,10 @@ export default class Schema {
    */
 
   callback() {
-    const versions = values(clone(this._versions)).sort((a, b) => a.version - b.version)
+    const versions = values(this._versions).sort((a, b) => a.version - b.version)
     return upgradeneeded((e, ...dbInfo) => {
       versions.forEach((versionSchema) => {
-        upgradeVersion(versionSchema, ...dbInfo)
+        upgradeVersion(versionSchema, e, ...dbInfo)
         versionSchema.callbacks.forEach((cb) => {
           cb(e)
         })
@@ -453,9 +459,13 @@ function upgradeneeded(cb) {
   }
 }
 
-function upgradeVersion(versionSchema, oldVersion, db, tr) {
+function upgradeVersion(versionSchema, e, oldVersion, db, tr) {
   if (oldVersion >= versionSchema.version) return
 
+  versionSchema.earlyCallbacks.forEach((cb) => {
+    cb(e)
+  })
+
   versionSchema.stores.forEach((s) => {
     // Only pass the options that are explicitly specified to createObjectStore() otherwise IE/Edge
     // can throw an InvalidAccessError - see https://msdn.microsoft.com/en-us/library/hh772493(v=vs.85).aspx