diff --git a/files/en-us/web/api/idbindex/getallrecords/index.md b/files/en-us/web/api/idbindex/getallrecords/index.md index 546ffacc93f002f..d97b492dd9b59e8 100644 --- a/files/en-us/web/api/idbindex/getallrecords/index.md +++ b/files/en-us/web/api/idbindex/getallrecords/index.md @@ -43,12 +43,12 @@ An options object whose properties can include: An {{domxref("IDBRequest")}} object on which subsequent events related to this operation are fired. -If the operation is successful, the value of the request's {{domxref("IDBRequest.result", "result")}} property is an {{jsxref("Array", "array")}} of objects representing all the records that match the given query, up to the number specified by `count` (if provided). +If the operation is successful, the value of the request's {{domxref("IDBRequest.result", "result")}} property is an {{jsxref("Array", "array")}} of {{domxref("IDBRecord")}} instances representing all the records that match the given query, up to the number specified by `count` (if provided). -Each object contains the following properties: +Each {{domxref("IDBRecord")}} instance contains the following properties: - `key` - - : A value representing the record's key. + - : A value representing the record's key in the index. - `primaryKey` - : A value representing the key of the record in the index's associated {{domxref("IDBObjectStore")}}. - `value` @@ -67,17 +67,38 @@ This method may raise a {{domxref("DOMException")}} of the following types: ## Examples +### Basic usage + +This example queries an {{domxref("IDBIndex")}} for up to 100 records whose `lastName` values come after `"Smith"`, with results sorted in reverse order. + +The code first creates a transaction on an {{domxref("IDBDatabase")}} named `db` (omitting the code to open the database), and then uses it to get an {{domxref("IDBObjectStore")}} containing a contacts list, and from that an `IDBIndex` on the `lastName` property. +It then calls `getAllRecords()` on the index, returning a {{domxref("IDBRequest")}} instance. +Event listeners are added to this request for the `success` and `error` events. +On success, the result `event.target.result` is logged (this is also available as `request.result`). +This result contains an array of `IDBRecord` instances. +Note that because this is a query on an `IDBIndex`, the `key` and `primaryKey` in each record may have different values: the `key` is the index key (here, the `lastName`), while the `primaryKey` is the record's key in the object store. + ```js -const query = IDBKeyRange.lowerBound("myKey", true); +// Create a transaction on the database and use it to get the contained store +const transaction = db.transaction(["contactsList"], "readonly"); const objectStore = transaction.objectStore("contactsList"); const myIndex = objectStore.index("lastName"); -const myRecords = (myIndex.getAllRecords({ +const query = IDBKeyRange.lowerBound("Smith", true); + +const request = myIndex.getAllRecords({ query, - count: "100", + count: 100, direction: "prev", -}).onsuccess = (event) => { - console.log("Records successfully retrieved"); +}); + +request.addEventListener("success", (event) => { + const myRecords = event.target.result; // Array of IDBRecord instances + console.log(myRecords); +}); + +request.addEventListener("error", (event) => { + console.error("Error retrieving records:", event.target.error); }); ``` diff --git a/files/en-us/web/api/idbobjectstore/getallrecords/index.md b/files/en-us/web/api/idbobjectstore/getallrecords/index.md index 2cec348cbc50ca4..4c7717223a3ba7c 100644 --- a/files/en-us/web/api/idbobjectstore/getallrecords/index.md +++ b/files/en-us/web/api/idbobjectstore/getallrecords/index.md @@ -8,10 +8,10 @@ browser-compat: api.IDBObjectStore.getAllRecords {{ APIRef("IndexedDB") }} -The **`getAllRecords()`** method of the {{domxref("IDBObjectStore")}} -interface retrieves all records (including primary keys and values) from the object store. +The **`getAllRecords()`** method of the {{domxref("IDBObjectStore")}} interface retrieves all records (including primary keys and values) from the object store. -`getAllRecords()` effectively combines the functionality of {{domxref("IDBObjectStore.getAllKeys", "getAllKeys()")}} and {{domxref("IDBObjectStore.getAll", "getAll()")}} by enumerating both primary keys and values at the same time. This combined operation enables certain data retrieval patterns to be significantly faster than alternatives such as iteration with cursors. +`getAllRecords()` effectively combines the functionality of {{domxref("IDBObjectStore.getAllKeys", "getAllKeys()")}} and {{domxref("IDBObjectStore.getAll", "getAll()")}} by enumerating both primary keys and values at the same time. +This combined operation enables certain data retrieval patterns to be significantly faster than alternatives such as iteration with cursors. ## Syntax @@ -43,14 +43,15 @@ An options object whose properties can include: An {{domxref("IDBRequest")}} object on which subsequent events related to this operation are fired. -If the operation is successful, the value of the request's {{domxref("IDBRequest.result", "result")}} property is an {{jsxref("Array", "array")}} of objects representing all records that match the given query, up to the number specified by `count` (if provided). +If the operation is successful, the value of the request's {{domxref("IDBRequest.result", "result")}} property is an {{jsxref("Array", "array")}} of {{domxref("IDBRecord")}} instances representing all records that match the given query, up to the number specified by `count` (if provided). -Each object contains the following properties: +Each {{domxref("IDBRecord")}} instance contains the following properties: - `key` - : A value representing the record's key. + This is identical to the `primaryKey` property. - `primaryKey` - - : The record's key; identical to the `key` property. + - : The record's primary key. - `value` - : A value representing the record's value. @@ -67,16 +68,37 @@ This method may raise a {{domxref("DOMException")}} of the following types: ## Examples +### Basic usage + +This example queries an {{domxref("IDBObjectStore")}} for up to 100 records whose keys come after `"myKey"`, with results sorted in reverse order. + +The code first creates a transaction on an {{domxref("IDBDatabase")}} named `db` (omitting the code to open the database), and then uses it to get an `IDBObjectStore` containing a contacts list. +It then calls `getAllRecords()` on the object store, returning a {{domxref("IDBRequest")}} instance. +Event listeners are added to this request for the `success` and `error` events. +On success, the result `event.target.result` is logged (this also available as `request.result`). +This result contains an array of `IDBRecord` instances. +Note that because this is a query on an `IDBObjectStore`, the `key` and `primaryKey` in each record have the same value. + ```js -const query = IDBKeyRange.lowerBound("myKey", true); +// Create a transaction on the database and use it to get the contained store +const transaction = db.transaction(["contactsList"], "readonly"); const objectStore = transaction.objectStore("contactsList"); -const myRecords = (objectStore.getAllRecords({ +const query = IDBKeyRange.lowerBound("myKey", true); + +const request = objectStore.getAllRecords({ query, - count: "100", + count: 100, direction: "prev", -}).onsuccess = (event) => { - console.log("Records successfully retrieved"); +}); + +request.addEventListener("success", (event) => { + const myRecords = event.target.result; // Array of IDBRecord instances + console.log(myRecords); +}); + +request.addEventListener("error", (event) => { + console.error("Error retrieving records:", event.target.error); }); ``` diff --git a/files/en-us/web/api/idbrecord/index.md b/files/en-us/web/api/idbrecord/index.md new file mode 100644 index 000000000000000..653853a3041695d --- /dev/null +++ b/files/en-us/web/api/idbrecord/index.md @@ -0,0 +1,80 @@ +--- +title: IDBRecord +slug: Web/API/IDBRecord +page-type: web-api-interface +browser-compat: api.IDBRecord +--- + +{{APIRef("IndexedDB")}} {{AvailableInWorkers}} + +The **`IDBRecord`** interface of the [IndexedDB API](/en-US/docs/Web/API/IndexedDB_API) represents a snapshot of a single record in an {{domxref("IDBObjectStore")}} or {{domxref("IDBIndex")}}. + +A request for records using {{domxref("IDBObjectStore.getAllRecords()")}} or {{domxref("IDBIndex.getAllRecords()")}} returns an {{domxref("IDBRequest")}} instance. +On success, the returned object's {{domxref("IDBRequest.result", "result")}} property is populated with an array of `IDBRecord` instances. + +## Instance properties + +- `key` {{ReadOnlyInline}} + - : A value representing the record's secondary key. + For an object store record, this will be the same as `primaryKey`. + For an index record, it will be the record's key within the index. +- `primaryKey` {{ReadOnlyInline}} + - : A value representing the record's primary key. + This key is used to represent the record in the {{domxref("IDBObjectStore")}}. +- `value` {{ReadOnlyInline}} + - : A value representing the record's value. + +## Instance methods + +_None._ + +## Examples + +### Basic usage + +This example queries an {{domxref("IDBObjectStore")}} for up to 100 records whose keys come after `"myKey"`, with results sorted in reverse order. + +The code first creates a transaction on an {{domxref("IDBDatabase")}} named `db` (omitting the code to open the database), and then uses it to get an `IDBObjectStore` containing a contacts list. +It then calls `getAllRecords()` on the object store, returning a {{domxref("IDBRequest")}} instance. +Event listeners are added to this request for the `success` and `error` events. +On success, the result `event.target.result` is logged (this is also available as `request.result`). +This result contains an array of `IDBRecord` instances. +Note that because this is a query on an `IDBObjectStore`, the `key` and `primaryKey` in each record have the same value. + +```js +// Create a transaction on the database and use it to get the contained store +const transaction = db.transaction(["contactsList"], "readonly"); +const objectStore = transaction.objectStore("contactsList"); + +const query = IDBKeyRange.lowerBound("myKey", true); + +const request = objectStore.getAllRecords({ + query, + count: 100, + direction: "prev", +}); + +request.addEventListener("success", (event) => { + const myRecords = event.target.result; // Array of IDBRecord instances + console.log(myRecords); +}); + +request.addEventListener("error", (event) => { + console.error("Error retrieving records:", event.target.error); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("IDBObjectStore.getAllRecords()")}} +- {{domxref("IDBIndex.getAllRecords()")}} +- [Using IndexedDB](/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB) +- Reference example: [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) ([View the example live](https://mdn.github.io/dom-examples/to-do-notifications/)). diff --git a/files/en-us/web/api/idbrequest/index.md b/files/en-us/web/api/idbrequest/index.md index 8fce1ce451311af..7ac11f3c9dcd643 100644 --- a/files/en-us/web/api/idbrequest/index.md +++ b/files/en-us/web/api/idbrequest/index.md @@ -7,15 +7,7 @@ browser-compat: api.IDBRequest {{APIRef("IndexedDB")}} {{AvailableInWorkers}} -The **`IDBRequest`** interface of the IndexedDB API provides access to results of asynchronous requests to databases and database objects using event handler attributes. Each reading and writing operation on a database is done using a request. - -The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the `IDBRequest` instance. - -All asynchronous operations immediately return an `IDBRequest` instance. Each request has a `readyState` that is set to the `'pending'` state; this changes to `'done'` when the request is completed or fails. When the state is set to `done`, every request returns a `result` and an `error`, and an event is fired on the request. When the state is still `pending`, any attempt to access the `result` or `error` raises an `InvalidStateError` exception. - -In plain words, all asynchronous methods return a request object. If the request has been completed successfully, the result is made available through the `result` property and an event indicating success is fired at the request ({{domxref("IDBRequest.success_event", "success")}}). If an error occurs while performing the operation, the exception is made available through the `error` property and an error event is fired ({{domxref("IDBRequest.error_event", "error")}}). - -The interface {{domxref("IDBOpenDBRequest")}} is derived from `IDBRequest`. +The **`IDBRequest`** interface of the IndexedDB API provides access to results of asynchronous requests to databases and database objects using event handler attributes. {{InheritanceDiagram}} @@ -47,9 +39,25 @@ Listen to these events using `addEventListener()` or by assigning an event liste - [`success`](/en-US/docs/Web/API/IDBRequest/success_event) - : Fired when an `IDBRequest` succeeds. +## Description + +The results of all database read and write operations are reported using a request object of this type. + +The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the `IDBRequest` instance. + +All asynchronous operations immediately return an `IDBRequest` instance. Each request has a `readyState` that is set to the `'pending'` state; this changes to `'done'` when the request is completed or fails. When the state is set to `done`, every request returns a `result` and an `error`, and an event is fired on the request. When the state is still `pending`, any attempt to access the `result` or `error` raises an `InvalidStateError` exception. + +In plain words, all asynchronous methods return a request object. If the request has been completed successfully, the result is made available through the `result` property and an event indicating success is fired at the request ({{domxref("IDBRequest.success_event", "success")}}). If an error occurs while performing the operation, the exception is made available through the `error` property and an error event is fired ({{domxref("IDBRequest.error_event", "error")}}). +The data in `result` depends on the operation that was called. + +The interface {{domxref("IDBOpenDBRequest")}} is derived from `IDBRequest`. + ## Example -In the following code snippet, we open a database asynchronously and make a request; `onerror` and `onsuccess` functions are included to handle the success and error cases. For a full working example, see our [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) app ([view example live](https://mdn.github.io/dom-examples/to-do-notifications/).) +### Basic usage + +In the following code snippet, we open a database asynchronously and make a request; event listeners for `error` and `success` are included to handle the success and error cases. +For a full working example, see our [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) app ([view example live](https://mdn.github.io/dom-examples/to-do-notifications/).) ```js let db; @@ -57,20 +65,20 @@ let db; // Let us open our database const DBOpenRequest = window.indexedDB.open("toDoList", 4); -// these two event handlers act on the database being -// opened successfully, or not -DBOpenRequest.onerror = (event) => { +// Handle the case where there is an error opening the database +DBOpenRequest.addEventListener("error", (event) => { note.appendChild(document.createElement("li")).textContent = "Error loading database."; -}; +}); -DBOpenRequest.onsuccess = (event) => { +// Handle the case where the database opens successfully +DBOpenRequest.addEventListener("success", (event) => { note.appendChild(document.createElement("li")).textContent = "Database initialized."; // store the result of opening the database. db = DBOpenRequest.result; -}; +}); ``` ## Specifications diff --git a/files/en-us/web/api/idbrequest/result/index.md b/files/en-us/web/api/idbrequest/result/index.md index b35e839940de838..a59cb6166763a2b 100644 --- a/files/en-us/web/api/idbrequest/result/index.md +++ b/files/en-us/web/api/idbrequest/result/index.md @@ -8,26 +8,26 @@ browser-compat: api.IDBRequest.result {{ APIRef("IndexedDB") }} {{AvailableInWorkers}} -The **`result`** read-only property of the -{{domxref("IDBRequest")}} interface returns the result of the request. +The **`result`** read-only property of the {{domxref("IDBRequest")}} interface returns the result of the request. + +The value depends on the request that was made. +For example, the {{domxref("IDBObjectStore.getAllRecords()")}} and {{domxref("IDBIndex.getAllRecords()")}} methods populate this property with an array of {{domxref("IDBRecord")}} instances on successful completion of the request. ## Value -any +any. ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown when attempting to access the property if the request - is not completed, and therefore the result is not available. + - : Thrown when attempting to access the property if the request is not completed, and therefore, the result is not available. ## Examples -The following example requests a given record title, `onsuccess` gets the -associated record from the {{domxref("IDBObjectStore")}} (made available -as `objectStoreTitleRequest.result`), updates -one property of the record, and then puts the updated record back into the object -store. For a full working example, see our [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) app ([View the example live](https://mdn.github.io/dom-examples/to-do-notifications/)). +### Basic usage + +The following example requests a given record title. On success, the associated record is retrieved from the {{domxref("IDBObjectStore")}} (made available as `objectStoreTitleRequest.result`), one property of the record is updated, and then the updated record is put back into the object store. +For a full working example, see our [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) app ([View the example live](https://mdn.github.io/dom-examples/to-do-notifications/)). ```js const title = "Walk dog"; @@ -40,7 +40,7 @@ const objectStore = db // Get the to-do list object that has this title as its title const objectStoreTitleRequest = objectStore.get(title); -objectStoreTitleRequest.onsuccess = () => { +objectStoreTitleRequest.addEventListener("success", () => { // Grab the data object returned as the result const data = objectStoreTitleRequest.result; @@ -53,10 +53,10 @@ objectStoreTitleRequest.onsuccess = () => { // When this new request succeeds, run the displayData() // function again to update the display - updateTitleRequest.onsuccess = () => { + updateTitleRequest.addEventListener("success", () => { displayData(); - }; -}; + }); +}); ``` ## Specifications diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index e5659e31e995733..75471eec8eba966 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -988,6 +988,7 @@ "IDBKeyRange", "IDBObjectStore", "IDBOpenDBRequest", + "IDBRecord", "IDBRequest", "IDBTransaction", "IDBVersionChangeEvent" diff --git a/package-lock.json b/package-lock.json index 1db41ad068c226f..754879d1ab9e769 100644 --- a/package-lock.json +++ b/package-lock.json @@ -34,7 +34,7 @@ "lefthook": "^2.1.9", "markdownlint-cli2": "0.23.0", "markdownlint-rule-search-replace": "1.2.0", - "node-html-parser": "^8.0.4", + "node-html-parser": "^9.0.0", "parse-diff": "^0.12.0", "prettier": "3.9.4", "tempy": "^3.2.0", @@ -7376,9 +7376,9 @@ } }, "node_modules/node-html-parser": { - "version": "8.0.4", - "resolved": "https://registry.npmjs.org/node-html-parser/-/node-html-parser-8.0.4.tgz", - "integrity": "sha512-w2YxujN/TqrSIWGVNW/fVgKKfAyQeHMXCvnKZI0owLnfP0tfjdLecUoy9zhOMZGoEFk6eP5qSDyvUarjPl3bwQ==", + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/node-html-parser/-/node-html-parser-9.0.0.tgz", + "integrity": "sha512-MhdaHPyxnyYu/sf0TpiRvDnTrkum0UKHC7FdbDGIUQNlx3I7xzwXoyV0eMUMv/XU+lkJT1glOUzpDPq7b2p1Ew==", "dev": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 8d2534c85a6f30b..4f8a22c92fd4a93 100644 --- a/package.json +++ b/package.json @@ -74,7 +74,7 @@ "lefthook": "^2.1.9", "markdownlint-cli2": "0.23.0", "markdownlint-rule-search-replace": "1.2.0", - "node-html-parser": "^8.0.4", + "node-html-parser": "^9.0.0", "parse-diff": "^0.12.0", "prettier": "3.9.4", "tempy": "^3.2.0",