{"id":19114594,"url":"https://github.com/goodguyry/indexedjs","last_synced_at":"2026-06-20T22:31:02.092Z","repository":{"id":21104552,"uuid":"24404970","full_name":"goodguyry/IndexedJS","owner":"goodguyry","description":"A wrapper for IndexedDB.","archived":false,"fork":false,"pushed_at":"2015-10-12T03:56:43.000Z","size":213,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-03T06:54:43.194Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goodguyry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-24T07:25:35.000Z","updated_at":"2015-02-08T07:38:46.000Z","dependencies_parsed_at":"2022-08-25T12:40:29.087Z","dependency_job_id":null,"html_url":"https://github.com/goodguyry/IndexedJS","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2FIndexedJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2FIndexedJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2FIndexedJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2FIndexedJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goodguyry","download_url":"https://codeload.github.com/goodguyry/IndexedJS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240170107,"owners_count":19759145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T04:43:53.569Z","updated_at":"2026-06-02T14:30:16.576Z","avatar_url":"https://github.com/goodguyry.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"IndexedJS\n========\nA no-frills wrapper for [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).\n\n**Distributions**\n\nThe [production version](https://github.com/goodguyry/IndexedJS/blob/master/dist/IndexedJS.min.js) (1282 bytes gzipped) and [development version](https://github.com/goodguyry/IndexedJS/blob/master/src/IndexedJS.js).\n\n# Usage\n\n**Contents**\n\n- [Creating and opening the database](#creating-and-opening-the-database)\n- [DOM Event handlers and ``this``](#dom-event-handlers-and-this)\n- [Querying the ObjectStore](#querying-the-objectstore)\n  - [Options](#options)\n  - [Using a cursor](#using-a-cursor)\n  - [Setting a keyRange](#setting-a-keyrange)\n  - [Collecting values from the cursor](#collecting-values-from-the-cursor)\n- [Adding to/updating the ObjectStore](#adding-toupdating-the-objectstore)\n- [Deleting from the ObjectStore](#deleting-from-the-objectstore)\n- [Todo](#todo)\n\n## Creating and opening the database\n\n[IDBFactory reference](https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory)\n\nTo create a new database, declare an object with properties for each of the required IndexedDB values, as well as additional values based on the desired schema.\n\n### Options\n\n**name**\n\nType: ``String``\n\nDefault: ``null``\n\nThe name of the database\n\n**version**\n\nType: ``Number``\n\nDefault: ``null``\n\nThe database version number\n\n**store**\n\nType: ``String``\n\nDefault: ``null``\n\nThe name given to the ObjectStore\n\n**keyPath**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nThe keyPath tells the browser what to use as the key\n\n**autoIncrement**\n\nType: ``Boolean``\n\nDefault: ``false``\n\nTo use an auto-incremented key, rather than manually assign values.\n\n**indexes**\n\nType: ``Object``\n\nDefault: ``null``\n\nThe ``index`` object's properties are the index names, and property values are whether or not they should be unique (``Boolean``).\n\n```javascript\n\n/* Initialize the database */\n\nvar init = {\n  name: \"Albums\",\n  version: 1,\n  store: \"Rock\",\n  keyPath: \"key\",\n  indexes: {\n    // indexName: Unique\n    band: false,\n    title: false\n  },\n  onsuccess: function(e) {\n    // onsuccess callback\n    console.log('Database open');\n  },\n  onerror: function(e) {\n    // onerror callback\n    console.dir(e.target.errorCode);\n  }\n};\n```\n\nThen instantiate a new IndexedJS object, passing in the declared object. Note the ``onsuccess`` and ``onerror`` handlers passed into ``new IndexedJS()`` are used by the ``IndexedJS.open`` method.\n\n```javascript\nvar RockAlbums = new IndexedJS(init);\n```\n\n## DOM Event handlers and ``this``\n\n**onsuccess**\n\n_key \u0026 index queries_: ``this`` refers to the object found in the ObjectStore.\n\n_cursor queries_: ``this`` refers to the ``cursor`` itself, which give access to the ``cursor`` properties (``source``, ``direction``, ``key`` and ``primaryKey``) and methods (``delete`` and ``update``).\n\n**oncomplete**\n\n``this`` refers to the options object passed into ``IndexedJS.query()``.\n\n## Querying the ObjectStore\n\n```javascript\nIndexedJS.query(Object [, Array]);\n```\n\nQueries are executed via the ``IndexedJS.query`` method. The type of query depends on the object properties passed in.\n\nThe ``Array`` passed as the optional second argument is the list of ObjectStores to query. At them moment, there's no support for creating multiple ObjectStores, so there's no need to specify - it's implied (support for multiple ObjectStores in the works).\n\n### Options\n\n**mode**\n\nType: ``String``\n\nDefault: ``\"readonly\"``\n\nTo interact with objects in the ObjectStore, set the mode to ``\"readwrite\"``.\n\n**key**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nQueries for the specified key only; overrides ``index`` setting, overridden by ``cursor`` settings\n\n**index**\n\nType: ``Object``\n\nDefault: ``false``\n\nThe ``index`` object's property is the index name, and property value is the index value being queried for; ``index`` settings are overridden by ``key`` and ``cursor`` settings.\n\n```javascript\n/* IndexedJS.query() by index */\n\nRockAlbums.query({\n  mode: \"readwrite\",\n  index: {\n    // Find Houses of the Holy by the mighty Zep\n    title: \"Houses of the Holy\"\n  },\n  onsuccess: function() {\n    // request.onsuccess\n  },\n  oncomplete: function() {\n    // transaction.complete\n  },\n  onerror: function() {\n    // request.onerror\n  }\n});\n```\n\n#### Using a cursor\n\n[IDBCursor Reference](https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor)\n\n**cursor**\n\nType: ``Object``\n\nDefault: ``false``\n\nTo use a cursor, include the ``cursor`` object in the options passed to the ``IndexedJS.query`` method. The ``cursor`` settings overrides ``key`` and ``index`` queries. The property options are as follows:\n\n**cursor.bound**\n\nType: ``Boolean``\n\nDefault: ``null``\n\nSet the ``bound`` property to ``false`` to cursor over all objects in the ObjectStore with no IDBKeyRange. Set to ``true`` to give yourself something to debug ;)\n\n**cursor.advance**\n\nType: ``Number``\n\nDefault: ``false``\n\nSet the ``advance`` property to advance the cursor by the specified number of places. When not set, the cursor will ``continue``.\n\n#### Setting a keyRange\n\n[IDBKeyRange reference](https://developer.mozilla.org/en-US/docs/Web/API/IDBKeyRange)\n\nTo set a lowerBound or upperBound keyRange, set the ``lower`` or ``upper`` property's value to the desired key. Use the ``include`` property to set whether or not to include the passed key in the range.\n\n**cursor.lower**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nThe lowerBound keyRange cursors over all keys _starting with_ the specified key, conditionally including the specified key.\n\n**cursor.upper**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nThe upperBound keyRange cursors over all keys _up to_ the specified key, conditionally including the specified key.\n\n**cursor.include**\n\nType: ``Boolean``\n\nDefault: ``false``\n\nWhether or not to include the specified key in the cursor iteration.\n\n**Cursor between**\n\nTo cursor through keys _between_ the lowerBound and upperBound, set both and use an array of values for the ``include`` property; the first of which for the ``lower`` key, the second for the ``upper`` key.\n\n**cursor.only**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nThe ``only`` property only returns the object with the desired key.\n\n```javascript\n\n/* IndexedJS.query - lowerBound */\n\nRockAlbums.query({\n  cursor: {\n    lower: 1410232894030,\n    include: false\n  },\n  onsuccess: function() {\n    // request.onsuccess\n  },\n  oncomplete: function() {\n    // transaction.complete\n  },\n  onerror: function() {\n    // request.onerror\n  }\n});\n```\n\n#### Collecting values from the cursor\n\nIt's often important to collect values as the cursor iterates over the keys.\n\n\n```javascript\n\n/* Collecting values from the cursor */\n\nvar opts = {\n  // the array in which to collect the titles\n  titles: [],\n  cursor: {\n    // cursor over all keys\n    bound: false\n  },\n  onsuccess: function() {\n    // collect the titles\n    opts.titles.push(this.title);\n  },\n  oncomplete: function() {\n    // this now refers to the opts object\n    for (var i = 0; i \u003c this.titles.length; i++) {\n      // do something with the titles\n    }\n  }\n};\n\nRockAlbums.query(opts);\n```\n\nOr, of course, an array could be created outside of the function and used in the same manner. As always, do whatever works best for the project.\n\n## Adding to/updating the ObjectStore\n\n```javascript\nIndexedJS.add(Object [, Array]);\n```\n\nFor the ``add`` method, the mode is automatically ``\"readwrite\"`` and cannot be overridden.\n\nAs with the ``IndexedJS.query`` method, the ``Array`` passed as the optional second argument is the list of ObjectStores to query. At them moment, there's no support for creating multiple ObjectStores, so there's no need to specify - it's implied (support for multiple ObjectStores in the works).\n\n### Options\n\n**data**\n\nType: ``Object``\n\nDefault: ``{}``\n\nAdd the ``data`` object to the options in order to pass in values to save. For updates, the ``data`` object must contain at least the key for the related object.\n\n```javascript\n\n/* IndexedJS.add() */\n\n// set up the `presence` object with new or updated values\nvar presence = {};\npresence.year = 1976;\npresence.key = \"7567-92439-2\";\n\nRockAlbums.add({\n  data: presence,\n  onsuccess: function() {\n    // handle events\n  },\n  oncomplete: function() {\n    // handle events\n  }\n});\n```\n\n## Deleting from the ObjectStore\n\n```javascript\nIndexedJS.delete(Object [, Array]);\n```\n\nFor the ``delete`` method, the mode is automatically ``\"readwrite\"`` and cannot be overridden.\n\nAs with the ``IndexedJS.query`` method, the ``Array`` passed as the optional second argument is the list of ObjectStores to query. At them moment, there's no support for creating multiple ObjectStores, so there's no need to specify - it's implied (support for multiple ObjectStores in the works).\n\n### Options\n\n**key**\n\nType: ``Number`` or ``String``\n\nDefault: ``false``\n\nPass the ``key`` for the object to be deleted.\n\n```javascript\n\n/* IndexedJS.delete() */\n\n// delete the 2007 release of \"Song Remains the Same\" on principle\nRockAlbums.add({\n  key: \"8122-79981-2\",\n  onsuccess: function() {\n    // handle events\n  },\n  oncomplete: function() {\n    // handle events\n  }\n});\n```\n\n\n## Todo\n\n- Add support for [IDBObjectStore.openKeyCursor](https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore.openKeyCursor)\n\n\n### Changelog:\n\n**v1.0.0**\n\n- It is no longer necessary to call the ``IndexedJS.open()`` method after instantiation.\n- Added backward compatibility for IDBDatabase.transaction\n- Changed ``this`` for ``cursor.onsuccess`` to refer to the cursor itself to gain access to cursor properties (``source``, ``direction``, ``key`` and ``primaryKey``)\n- Added support for ``cursor.advance`` method\n- Added support for ``cursor.delete`` and ``cursor.update`` methods\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodguyry%2Findexedjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoodguyry%2Findexedjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodguyry%2Findexedjs/lists"}