4.7. The IDBKeyRange interface

The [IDBKeyRange](#idbkeyrange) interface represents a key range.

  1. [Exposed=(Window,Worker)]
  2. interface IDBKeyRange {
  3.   readonly attribute any lower;
  4.   readonly attribute any upper;
  5.   readonly attribute boolean lowerOpen;
  6.   readonly attribute boolean upperOpen;
  7.  
  8.   // Static construction methods:
  9.   [NewObject] static IDBKeyRange only(any value);
  10.   [NewObject] static IDBKeyRange lowerBound(any lower, optional boolean open = false);
  11.   [NewObject] static IDBKeyRange upperBound(any upper, optional boolean open = false);
  12.   [NewObject] static IDBKeyRange bound(any lower,
  13.                                        any upper,
  14.                                        optional boolean lowerOpen = false,
  15.                                        optional boolean upperOpen = false);
  16.  
  17.   boolean _includes(any key);
  18. };

Note: When mapping the _includes identifier to ECMAscript, the leading U+005F LOW LINE (“_“) character should be removed. A leading “_“ is used to escape the identifier from looking like a reserved word (in this case, the includes keyword).

range . [lower](#dom-idbkeyrange-lower)

Returns lower bound, or undefined if none.

range . [upper](#dom-idbkeyrange-upper)

Returns upper bound, or undefined if none.

range . [lowerOpen](#dom-idbkeyrange-loweropen)

Returns true if the lower open flag is set, and false otherwise.

range . [upperOpen](#dom-idbkeyrange-upperopen)

Returns true if the upper open flag is set, and false otherwise.

The lower attribute’s getter must return result of running the steps to convert a key to a value with the lower bound if it is not null, or undefined otherwise.

The upper attribute’s getter must return the result of running the steps to convert a key to a value with the upper bound if it is not null, or undefined otherwise.

The lowerOpen attribute’s getter must return true if the lower open flag is set, and false otherwise.

The upperOpen attribute’s getter must return true if the upper open flag is set, and false otherwise.

range = [IDBKeyRange](#idbkeyrange) . [only](#dom-idbkeyrange-only)(key)

Returns a new [IDBKeyRange](#idbkeyrange) spanning only key.

range = [IDBKeyRange](#idbkeyrange) . [lowerBound](#dom-idbkeyrange-lowerbound)(key [, open = false])

Returns a new [IDBKeyRange](#idbkeyrange) starting at key with no upper bound. If open is true, key is not included in the range.

range = [IDBKeyRange](#idbkeyrange) . [upperBound](#dom-idbkeyrange-upperbound)(key [, open = false])

Returns a new [IDBKeyRange](#idbkeyrange) with no lower bound and ending at key. If open is true, key is not included in the range.

range = [IDBKeyRange](#idbkeyrange) . [bound](#dom-idbkeyrange-bound)(lower, upper [, lowerOpen = false [, upperOpen = false]])

Returns a new [IDBKeyRange](#idbkeyrange) spanning from lower to upper. If lowerOpen is true, lower is not included in the range. If upperOpen is true, upper is not included in the range.

The only(value) method, when invoked, must run these steps:

  1. Let key be the result of running the steps to convert a value to a key with value. Rethrow any exceptions.

  2. If key is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  3. Create and return a new key range containing only key.

The lowerBound(lower, lowerOpen) method, when invoked, must run these steps:

  1. Let lowerKey be the result of running the steps to convert a value to a key with lower. Rethrow any exceptions.

  2. If lowerKey is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  3. Create and return a new key range with lower bound set to lowerKey, lower open flag set if lowerOpen is true, upper bound set to null and upper open flag set.

The upperBound(upper, upperOpen) method, when invoked, must run these steps:

  1. Let upperKey be the result of running the steps to convert a value to a key with upper. Rethrow any exceptions.

  2. If upperKey is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  3. Create and return a new key range with lower bound set to null, lower open flag set, upper bound set if upperKey, and upper open flag set to upperOpen.

The bound(lower, upper, lowerOpen, upperOpen) method, when invoked, must run these steps:

  1. Let lowerKey be the result of running the steps to convert a value to a key with lower. Rethrow any exceptions.

  2. If lowerKey is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  3. Let upperKey be the result of running the steps to convert a value to a key with upper. Rethrow any exceptions.

  4. If upperKey is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  5. If lowerKey is greater than upperKey, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  6. Create and return a new key range with lower bound set to lowerKey, lower open flag set if lowerOpen is true, upper bound set to upperKey and upper open flag set if upperOpen is true.

range . [includes](#dom-idbkeyrange-includes)(key)

Returns true if key is included in the range, and false otherwise.

The includes(key) method, when invoked, must run these steps:

  1. Let k be the result of running the steps to convert a value to a key with key. Rethrow any exceptions.

  2. If k is invalid, throw a “[DataError](https://www.w3.org/TR/WebIDL-1/#dataerror)“ [DOMException](https://www.w3.org/TR/WebIDL-1/#idl-DOMException).

  3. Return true if k is in this range, and false otherwise.

🚧 The [includes()](#dom-idbkeyrange-includes) method is new in this edition. It is supported in Chrome 52, Firefox 47, and Safari 10.1. 🚧