feat: Add outOfRange option

Author: nzakas

README.md

@@ -26,7 +26,7 @@ const items = new ArrayWithDefault({
 console.log(items[1]);      // 0
 ```
 
-The primary use case for this class is when an array is an optional argument for a function, but using an empty array won't work.
+The primary use case for this class is when an array is an optional argument for a function or when an array may have holes.
 
 ## Usage
 
@@ -81,6 +81,7 @@ After importing, create a new instance of `ArrayWithDefault`. The constructor ex
 * `default` **(required)** - the default value to return for the missing items.
 * `elements` - an optional iterable object used to populate the array.
 * `length` - an optional value to set the array's `length` property to.
+* `outOfRange` - an optional value that, when set to `true`, indicates that numeric indices after the end of the array should also return the default value.
 
 Here are some examples:
 
@@ -115,6 +116,19 @@ console.log(emptyItems[4]);     // 0
 // items past the end still return undefined
 console.log(emptyItems[5]);     // undefined
 
+const numbers = new ArrayWithDefault({
+    default: 0,
+    elements: [1, 2, 3],
+    outOfRange: true
+});
+
+// all elements return 0
+console.log(emptyItems[0]);     // 1
+console.log(emptyItems[1]);     // 2
+console.log(emptyItems[2]);     // 3
+console.log(emptyItems[3]);     // 0
+console.log(emptyItems[4]);     // 0
+console.log(emptyItems[5]);     // 0
 ```
 
 ## Developer Setup

src/array-with-default.js

@@ -16,6 +16,8 @@ export class ArrayWithDefault extends Array {
      * @param {Array} [options.elements] The array elements to prepopulate into
      *      the array.
      * @param {number} [options.length] The number of elements in the array.
+     * @param {boolean} [options.outOfRange=false] When true, the default value
+     *      with also be returned for indices after the last element.
      */
     constructor(options = {}) {
         super();
@@ -55,7 +57,7 @@ export class ArrayWithDefault extends Array {
                  */
                 if (
                     Number.isInteger(index) && 
-                    index < target.length &&
+                    (options.outOfRange || index < target.length) &&
                     value === undefined
                 ) {
                     return options.default;

tests/array-with-default.test.js

@@ -143,15 +143,44 @@ describe("ArrayWithDefault", () => {
             expect(itemsWithDefault).to.deep.equal([0, 0, 0, 0, 0]);
         });
 
-        it("should return default when element is missing", () => {
+        it("should set length when elements are passed", () => {
 
             const itemsWithDefault = new ArrayWithDefault({
+                elements: [1, 2, 3],
                 length: 5,
                 default: 0
             });
 
-            expect(itemsWithDefault).to.deep.equal([0, 0, 0, 0, 0]);
+            expect(itemsWithDefault.length).to.equal(5);
+            expect(itemsWithDefault).to.deep.equal([1, 2, 3, 0, 0]);
+        });
+    });
+
+    describe("outOfRange", () => {
+
+        it("should return default for elements after the last element", () => {
+
+            const itemsWithDefault = new ArrayWithDefault({
+                default: 0,
+                outOfRange: true
+            });
+
+            expect(itemsWithDefault[0]).to.equal(0);
+            expect(itemsWithDefault[1]).to.equal(0);
+        });
+
+        it("should return default for elements after the last element when length is set", () => {
+
+            const itemsWithDefault = new ArrayWithDefault({
+                default: 0,
+                length: 5,
+                outOfRange: true
+            });
+
+            expect(itemsWithDefault[0]).to.equal(0);
+            expect(itemsWithDefault[5]).to.equal(0);
         });
+
     });
 
     describe("concat()", () => {