feat: reset and increment sequences

docs/sequences.md

@@ -7,6 +7,8 @@ Massive only loads independent sequences and ignores those which back table prim
 <!-- vim-markdown-toc GFM -->
 
 * [lastValue](#lastvalue)
+* [nextValue](#nextvalue)
+* [reset](#reset)
 
 <!-- vim-markdown-toc -->
 
@@ -19,3 +21,24 @@ db.mysequence.lastValue().then(val => {
   // val is a number
 });
 ```
+
+## nextValue
+
+`nextValue` increments the sequence counter and returns the latest value.
+
+```javascript
+db.mysequence.nextValue().then(val => {
+  // val is a number
+});
+```
+
+## reset
+
+`reset` starts the sequence over at 1 (if called without arguments) or a value of your choosing.
+
+```javascript
+db.mysequence.reset(123).then(() => {
+  // reset does not return a value, but the next value
+  // acquired from the sequence will be 123.
+});
+```

lib/sequence.js

@@ -12,9 +12,8 @@ const Select = require('./statement/select');
  * @param {Object} spec - An {@linkcode Entity} specification representing a
  * sequence object:
  * @param {Object} spec.db - A {@linkcode Database}.
- * @param {String} spec.name - The table or view's name.
- * @param {String} spec.schema - The name of the schema owning the table or
- * view.
+ * @param {String} spec.name - The sequence's name.
+ * @param {String} spec.schema - The name of the schema owning the sequence.
  */
 const Sequence = function () {
   Entity.apply(this, arguments);
@@ -23,12 +22,32 @@ const Sequence = function () {
 util.inherits(Sequence, Entity);
 
 /**
- * Get the last value for the sequence.
+ * Get the last value the sequence returned.
  *
  * @return {Promise} The last sequence value.
  */
 Sequence.prototype.lastValue = function () {
   return this.db.query(new Select(this, {}, {fields: ['last_value'], single: true})).then(v => v.last_value);
 };
 
+/**
+ * Increment the sequence counter and return the next value.
+ *
+ * @return {Promise} The next sequence value.
+ */
+Sequence.prototype.nextValue = function () {
+  return this.db.query(`SELECT nextval('${this.delimitedFullName}')`).then(v => v[0].nextval);
+};
+
+/**
+ * Reset the sequence.
+ *
+ * @return {Promise} Nothing.
+ * @param {Number} [initialValue] - The new value with which to seed the
+ * sequence (default 1).
+ */
+Sequence.prototype.reset = function (initialValue = 1) {
+  return this.db.query(`ALTER SEQUENCE ${this.delimitedFullName} RESTART WITH $1`, [initialValue]);
+};
+
 module.exports = Sequence;

test/sequence/nextValue.js

@@ -0,0 +1,20 @@
+'use strict';
+
+describe('nextValue', function () {
+  let db;
+
+  before(function () {
+    return resetDb('sequences').then(instance => db = instance);
+  });
+
+  after(function () {
+    return db.instance.$pool.end();
+  });
+
+  it('gets the next value for a sequence', function* () {
+    const lastValue = yield db.one_counter.lastValue();
+    const nextValue = yield db.one_counter.nextValue();
+
+    assert.isAbove(Number(nextValue), Number(lastValue));
+  });
+});

test/sequence/reset.js

@@ -0,0 +1,33 @@
+'use strict';
+
+describe('reset', function () {
+  let db;
+
+  before(function () {
+    return resetDb('sequences').then(instance => db = instance);
+  });
+
+  after(function () {
+    return db.instance.$pool.end();
+  });
+
+  it('resets a sequence', function* () {
+    const nextVal = yield db.one_counter.nextValue();
+
+    assert.isAbove(Number(nextVal), 1);
+
+    yield db.one_counter.reset();
+
+    const postReset = yield db.one_counter.lastValue();
+
+    assert.equal(postReset, 1);
+  });
+
+  it('resets a sequence to a specific value', function* () {
+    yield db.one_counter.reset(123);
+
+    const postReset = yield db.one_counter.lastValue();
+
+    assert.equal(postReset, 123);
+  });
+});