{"id":17937743,"url":"https://github.com/indexeddbshim/indexeddbshim","last_synced_at":"2025-12-12T04:02:02.829Z","repository":{"id":3505926,"uuid":"4563126","full_name":"indexeddbshim/IndexedDBShim","owner":"indexeddbshim","description":"A polyfill for IndexedDB using WebSql","archived":false,"fork":false,"pushed_at":"2024-09-11T01:18:31.000Z","size":40949,"stargazers_count":974,"open_issues_count":17,"forks_count":190,"subscribers_count":49,"default_branch":"main","last_synced_at":"2025-05-04T02:01:53.508Z","etag":null,"topics":["indexeddb","indexeddbshim","javascript","support-indexeddb","websql"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indexeddbshim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["brettz9"],"issuehunt":"brettz9","custom":["https://www.paypal.me/brettzamir"]}},"created_at":"2012-06-05T17:29:56.000Z","updated_at":"2025-04-03T05:09:59.000Z","dependencies_parsed_at":"2023-12-07T23:31:37.953Z","dependency_job_id":"928f3ecf-8f89-4bee-8a29-0112c0d2e225","html_url":"https://github.com/indexeddbshim/IndexedDBShim","commit_stats":{"total_commits":826,"total_committers":54,"mean_commits":"15.296296296296296","dds":"0.31840193704600483","last_synced_commit":"56cf2ca3f5cdbe51ab9d47f0e5bca4ad5fa3b002"},"previous_names":["axemclion/indexeddbshim"],"tags_count":81,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexeddbshim%2FIndexedDBShim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexeddbshim%2FIndexedDBShim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexeddbshim%2FIndexedDBShim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexeddbshim%2FIndexedDBShim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indexeddbshim","download_url":"https://codeload.github.com/indexeddbshim/IndexedDBShim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149960,"owners_count":22022851,"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":["indexeddb","indexeddbshim","javascript","support-indexeddb","websql"],"created_at":"2024-10-28T23:07:19.127Z","updated_at":"2025-12-12T04:02:02.822Z","avatar_url":"https://github.com/indexeddbshim.png","language":"JavaScript","funding_links":["https://github.com/sponsors/brettz9","https://issuehunt.io/r/brettz9","https://www.paypal.me/brettzamir","https://issuehunt.io/r/indexeddbshim/indexeddbshim)--"],"categories":[],"sub_categories":[],"readme":"# IndexedDB Polyfill\n\n[![Build Status](https://img.shields.io/travis/indexeddbshim/IndexedDBShim.svg)](https://travis-ci.org/indexeddbshim/IndexedDBShim)\n[![Dependencies](https://img.shields.io/david/indexeddbshim/indexeddbshim.svg)](https://david-dm.org/indexeddbshim/indexeddbshim)\n[![devDependencies](https://img.shields.io/david/dev/indexeddbshim/indexeddbshim.svg)](https://david-dm.org/indexeddbshim/indexeddbshim?type=dev)\n[![npm](http://img.shields.io/npm/v/indexeddbshim.svg)](https://www.npmjs.com/package/indexeddbshim)\n[![CDNJS](https://img.shields.io/cdnjs/v/IndexedDBShim.svg)](https://cdnjs.com/libraries/indexeddbshim)\n\n[![Tests badge](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/badges/tests-badge.svg?sanitize=true)](badges/tests-badge.svg)\n[![Coverage badge](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/badges/coverage-badge.svg?sanitize=true)](badges/coverage-badge.svg)\n\n[![Known Vulnerabilities](https://snyk.io/test/github/indexeddbshim/indexeddbshim/badge.svg)](https://snyk.io/test/github/indexeddbshim/indexeddbshim)\n[![Total Alerts](https://img.shields.io/lgtm/alerts/g/indexeddbshim/indexeddbshim.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/indexeddbshim/indexeddbshim/alerts)\n[![Code Quality: Javascript](https://img.shields.io/lgtm/grade/javascript/g/indexeddbshim/indexeddbshim.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/indexeddbshim/indexeddbshim/context:javascript)\n\n[![License](https://img.shields.io/npm/l/indexeddbshim.svg)](LICENSE-APACHE)\n\n[![Licenses badge](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/badges/licenses-badge.svg?sanitize=true)](badges/licenses-badge.svg)\n\u003c!--\n[![Licenses dev badge](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/badges/licenses-badge-dev.svg?sanitize=true)](badges/licenses-badge-dev.svg)\n--\u003e\n(see also [licenses for dev. deps.](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/badges/licenses-badge-dev.svg?sanitize=true))\n\n\u003c!--[![issuehunt-to-marktext](https://issuehunt.io/static/embed/issuehunt-button-v1.svg)](https://issuehunt.io/r/indexeddbshim/indexeddbshim)--\u003e\n\n|[Live Demo (stable)!](https://raw.githack.com/indexeddbshim/indexeddbshim/v8.0.0/index.html) | [Live Demo (master)!](https://indexeddbshim.github.io/IndexedDBShim/) |\n| -------------- | ----------------- |\n\n__Use a single, indexable, offline storage API across all desktop and mobile\nbrowsers and Node.js.__\n\nEven if a browser natively supports [IndexedDB](http://w3c.github.io/IndexedDB/),\nyou may still want to use this shim.  Some native IndexedDB implementations are\n[very buggy](http://www.raymondcamden.com/2014/09/25/IndexedDB-on-iOS-8-Broken-Bad/).\nOthers are [missing certain features](http://codepen.io/cemerick/pen/Itymi).\nThere are also many minor inconsistencies between different browser\nimplementations of IndexedDB, such as how errors are handled, how transaction\ntiming works, how records are sorted, how cursors behave, etc.  Using this\nshim will ensure consistent behavior across all browsers.\n\n## Features\n\n- Optionally adds full IndexedDB support to any web browser that\n    [supports WebSQL](http://caniuse.com/#search=websql)\n- Does nothing if the browser already\n    [natively supports IndexedDB](http://caniuse.com/#search=indexeddb)\n- Can _optionally replace_ native IndexedDB on browsers with\n    [buggy implementations](http://www.raymondcamden.com/2014/09/25/IndexedDB-on-iOS-8-Broken-Bad/)\n- Works on __desktop__ and __mobile__ devices as well as __Node.js__ (courtesy of\n    [websql](https://www.npmjs.com/package/websql) which sits on top of SQLite3)\n- Works on __Cordova__ and __PhoneGap__ via the\n    [IndexedDB plug-in](http://plugins.cordova.io/#/package/com.msopentech.websql)\n    (Not recently tested)\n- This shim is basically an IndexedDB-to-WebSQL adapter.\n- More (though most likely now outdated) details about the project at\n    \u003chttp://nparashuram.com/IndexedDBShim\u003e\n\n## Installation\n\nYou can download the [development](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/dist/indexeddbshim.js)\nor\n[production (minified)](https://raw.githubusercontent.com/indexeddbshim/indexeddbshim/master/dist/indexeddbshim.min.js)\nscript, or install it using [NPM](https://docs.npmjs.com/getting-started/what-is-npm).\n\nFor Mac, you may need to have [CMake](https://cmake.org/download/) installed\nfor the SQLite3 install to work (See\n`Tools-\u003eHow to Install For Command Line Use`) as well as build SQLite3 from\nsource via `npm install --build-from-source` in the `node-sqlite3` directory.\nAlso make sure Python (2.7) is installed.\n\n### npm\n\n```shell\nnpm install indexeddbshim\n```\n\nor\n\n```shell\nyarn add indexeddbshim\n```\n\n## Browser set-up\n\nAdd the following scripts to your page:\n\n```html\n\u003cscript src=\"./node_modules/core-js-bundle/minified.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"./node_modules/indexeddbshim/dist/indexeddbshim.min.js\"\u003e\u003c/script\u003e\n```\n\nIf you need full Unicode compliance (handling special\nnon-alphanumeric identifiers in store and index names),\nuse the following instead:\n\n```html\n\u003cscript src=\"./node_modules/core-js-bundle/minified.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"./node_modules/indexeddbshim/dist/indexeddbshim-UnicodeIdentifiers.min.js\"\u003e\u003c/script\u003e\n```\n\n## Node set-up\n\n```js\nconst setGlobalVars = require('indexeddbshim');\n\nglobal.window = global; // We'll allow ourselves to use `window.indexedDB` or `indexedDB` as a global\nsetGlobalVars(); // See signature below\n```\n\n## ES6 Modules\n\n### Bundler for Browser\n\n```js\nimport setGlobalVars from 'indexeddbshim';\n```\n\n### Bundler for Node\n\n```js\nimport setGlobalVars from 'indexeddbshim/src/node-UnicodeIdentifiers';\n\n// Or without Unicode support\n// import setGlobalVars from 'indexeddbshim/src/node';\n```\n\n## Usage/API\n\nFor the browser scripts, if the browser already natively supports IndexedDB\nand is not known to be buggy, then the script won't do anything.\n\nOtherwise, assuming WebSQL is available, the script will add the\n[IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)\nto the browser (unless you use one of the non-invasive files, in which case\n`setGlobalVars` can be used to optionally add the API to an object of your\nchoosing; if you also wish Unicode support, you will need to add it yourself).\n\nEither way, you can use IndexedDB just like normal.\n[Here's an example](https://gist.github.com/BigstickCarpet/a0d6389a5d0e3a24814b).\n\n### setGlobalVars(\\\u003cwinObj or `null`\\\u003e, initialConfig)\n\nIn the non-invasive builds (and Node.js), globals are not automatically set.\nYou have the choice to set globals when you wish as well as to set the API\non an object of your choosing in place of setting globals.\n\nThis is done through `setGlobalVars()` (which is otherwise called in the\nbrowser builds automatically with no arguments).\n\nThis function defines `shimIndexedDB`, `indexedDB`, `IDBFactory`, etc. on\none of the following objects in order of precedence:\n\n1. The passed in `winObj` object if defined\n1. `window` (for Node, define `global.window = global;`)\n1. `self` (for web workers)\n1. `global` (for Node)\n1. A new empty object\n\nThe `initialConfig` argument, if present, should be an object whose keys\nare the config properties to set and its values are the config values (see\n`shimIndexedDB.__setConfig` below).\n\nIf you are adding your own `window.openDatabase` implementation, supplying\nit within `initialConfig` (keyed as `openDatabase`) will ensure that\n`shimIndexedDB.__useShim()` is auto-invoked for you if poor IndexedDB\nsupport is detected.\n\n### shimIndexedDB.\\__useShim();\n\nTo force IndexedDBShim to shim the browser's native IndexedDB (if our code\nis not already auto-shimming your browser when detecting poor browser\nsupport), add this method call to your script.\n\nOn browsers that support WebSQL, this line will _completely replace_ the\nnative IndexedDB implementation with the IndexedDBShim-to-WebSQL\nimplementation.\n\nOn browsers that _don't_ support WebSQL, but _do_ support IndexedDB, this\nline will patch many known problems and add missing features. For example,\non Internet Explorer, this will add support for compound keys.\n\nIf `CFG.addNonIDBGlobals` has been set (e.g., on the `initialConfig` argument\nof `setGlobalVars`), the other non-IndexedDB shims necessitated by this\nlibrary will be polyfilled as possible on the chosen \"global\" (i.e.,\n`ShimEvent`, `ShimCustomEvent`, `ShimEventTarget`, `ShimDOMException`,\nand `ShimDOMStringList`). Mostly useful for testing.\n\nIf `CFG.replaceNonIDBGlobals` is used, it will instead attempt to add,\nor if already present, overwrite these globals.\n\nIf `CFG.fullIDLSupport` has been set, the slow-performing\n`Object.setPrototypeOf` calls required for full WebIDL compliance will\nbe used. Probably only needed for testing or environments where full\nintrospection on class relationships is required.\nSee this [SO topic](http://stackoverflow.com/questions/41927589/rationales-consequences-of-webidl-class-inheritance-requirements)\n\n### shimIndexedDB.\\__forceClose([dbName], [connIdx], [msg])\n\nThe spec anticipates the [closing of a database connection with a forced flag](http://w3c.github.io/IndexedDB/#steps-for-closing-a-database-connection).\n\nThe spec also mentions [some circumstances](http://w3c.github.io/IndexedDB/#database-connection)\nwhere this may occur:\n\n\u003e A connection may be closed by a user agent in exceptional circumstances,\n\u003e for example due to loss of access to the file system, a permission change,\n\u003e or clearing of the origin’s storage.\n\nSince the latter examples are under the browser's control, this method may\nbe more useful on the server or for unit-testing.\n\nIf the first argument, `dbName` is missing (or `null` or `undefined`),\nall connections to all databases will be force-closed.\n\nIf the second argument, `connIdx` is missing (or `null` or `undefined`),\nall connections with the given name will be force-closed. It can\nalternatively be an integer representing a 0-based index to indicate a\nspecific connection to close.\n\nThe third argument `msg` will be appended to the `AbortError` that will be\ntriggered on the transactions of the connection.\n\nIndividual `IDBDatabase` database instances can also be force-closed\nwith a particular message:\n\n```js\ndb.__forceClose(msg);\n```\n\n### shimIndexedDB.\\__setConnectionQueueOrigin(origin = getOrigin())\n\nEstablishes a `connectionQueue` for the supplied (or current) origin.\n\nThe queue is otherwise only keyed to the detected origin on the\nloading of the IndexedDBShim script, though this is usually the\ndesired behavior.\n\n### shimIndexedDB.\\__debug(boolean)\n\nThe IndexedDB polyfill has sourcemaps enabled, so the polyfill can be debugged\neven if the minified file is included.\n\nTo print out detailed debug messages, add this line to your script:\n\n```js\nshimIndexedDB.__debug(true);\n```\n\n### shimIndexedDB.\\__setConfig()\n\nRather than using globals, a method has been provided to share state across\nIndexedDBShim modules.\n\nConfiguration can be set early in the non-invasive browser and Node builds\nvia the second argument to `setGlobalVars()` (see its definition above).\n\nIts signature (for setting configuration after `shimIndexedDB` is created) is:\n\n```js\nshimIndexedDB.__setConfig({\n    property: value, property2: value2, ...otherProperties\n});\n```\n\nor:\n\n```js\nshimIndexedDB.__setConfig(property, value);\n```\n\n### `createDOMException(name, message)`\n\nA utility for creating a `DOMException` instance. Attempts to use any\navailable native implementation.\n\n#### Configuration options\n\nThe available properties relevant to browser or Node are:\n\n- __DEBUG__ - Boolean (equivalent to calling `shimIndexedDB.__debug(val)`)\n- __cacheDatabaseInstances__ - Config to ensure that any repeat\n    `IDBFactory.open` call to the same name and version (assuming\n    no deletes or aborts causing rollbacks) will reuse the same SQLite\n    `openDatabase` instance.\n- __checkOrigin__ - Boolean on whether to perform origin checks in `IDBFactory`\n    methods (`open`, `deleteDatabase`, `databases`); effectively\n    defaults to true (must be set to `false` to cancel checks); for Node\n    testing, you will either need to define a `location` global from which\n    the origin value can be found or set this property to `false`.\n- __UnicodeIDStart__ and __UnicodeIDContinue__ - Invocation of\n    `createObjectStore` and `createIndex` calls for validation of key paths.\n    The specification technically allows all\n    `IdentifierName`](https://tc39.github.io/ecma262/#prod-IdentifierName)\n    strings, but as this requires a [very large regular expression](https://gist.github.com/brettz9/b4cd6821d990daa023b2e604de371407),\n    it is replaced by default with `[$A-Z_a-z]` and `[$0-9A-Z_a-z]`,\n    respectively. Note that these are and must be expressed as strings,\n    not `RegExp` objects. You can use this configuration to change the default\n    to match the spec or as you see fit. In the future we may allow the spec\n    behavior via optional dynamic loading of an internal module.\n- __registerSCA__ - For data created in 3.* versions of IndexedDBShim to\n    continue to work with the more recent version of typeson-registry we\n    are using (specifically its Structured Cloning Algorithm), set this\n    property to a callback which is passed the current typeson-registry\n    structured cloning algorithm representation and return its own to be\n    passed to `typeson.register`. See the library\n    [typeson-registry-sca-reverter](https://github.com/brettz9/typeson-registry-sca-reverter)\n    for a function that can do this and check it for updates if you are\n    using it in case needed to work against new updates of IndexedDBShim.\n- __fullIDLSupport__ - If set to `true`, the slow-performing\n    `Object.setPrototypeOf` calls required for full WebIDL compliance will\n    be used. Probably only needed for testing or environments where full\n    introspection on class relationships is required.\n    See this [SO topic](http://stackoverflow.com/questions/41927589/rationales-consequences-of-webidl-class-inheritance-requirements)\n- __win__,  Object on which there may be an `openDatabase` method (if any)\n    for WebSQL; Defaults to `window` or `self` in the browser and for Node,\n    it is set by default to [`node-websql`](https://github.com/nolanlawson/node-websql).\n    If you are intending on adding your own `openDatabase` implementation,\n    please note that (for the sake of Node), we rely on supplying an additional\n    non-WebSQL-standard callback argument to *WebSQL* `transaction` or\n    `readTransaction` calls in our `node-websql` fork to allow it to prolong\n    the transaction (to last through our IndexedDB transaction) and to provide\n    rollback functionality. (See\n    \u003chttps://github.com/axemclion/IndexedDBShim/issues/296\u003e, however, for\n    a remaining issue this fix does not currently overcome.)\n- __cursorPreloadPackSize__ - Number indicating how many records to preload for\n    caching of `IDBCursor.continue` calls. Defaults to 100.\n- __DEFAULT_DB_SIZE__ - Used as estimated size argument (in bytes) to\n    underlying WebSQL `openDatabase` calls. Defaults to `4 * 1024 * 1024` or\n    `25 * 1024 * 1024` in Safari (apparently necessary due to Safari creating\n    larger files and possibly also due to Safari not completing the storage\n    of all records even after permission is given). Has no effect in Node\n    (using [`node-websql`](https://github.com/nolanlawson/node-websql)),\n    and its use in WebSQL-compliant browsers is implementation dependent (the\n    browser may use this information to suggest the use of this quota to the\n    user rather than prompting the user regularly for say incremental 5MB\n    permissions).\n- __useSQLiteIndexes__ - Whether to create indexes on SQLite tables (and also\n    whether to try dropping). Indexes can increase file size and slow\n    performance on tables involving many write operations, but can speed\n    performance for retrieval. Defaults to `false`.\n- __avoidAutoShim__ - Where WebSQL is detected but where `indexedDB` is\n    missing or poor support is known (non-Chrome Android or\n    non-Safari iOS9), the shim will be auto-applied without\n    `shimIndexedDB.__useShim()`. Set this to `true` to avoid forcing\n    the shim for such cases.\n\nThe following config are mostly relevant to Node but has bearing on the\nbrowser, particularly if one changes the defaults.\n\n- __fs__ - File system module with `unlink` to remove deleted database files.\n    Auto-set by Node distributions.\n- __addNonIDBGlobals__ - If set to `true` will polyfill the \"global\" with\n    non-IndexedDB shims created by and sometimes returned publicly by\n    the library. These include `ShimEvent`, `ShimCustomEvent`,\n    `ShimEventTarget`, `ShimDOMException`, and `ShimDOMStringList`.\n    Mostly useful for debugging (and in Node where these\n    are not available by default).\n- __replaceNonIDBGlobals__ - Similar to `addNonIDBGlobals` but will attempt\n    to add the values unprefixed and overwrite if possible. Mostly for\n    testing.\n- __escapeDatabaseName__ - Due to the Node implementation's reliance on\n    `node-websql`/`node-sqlite3` which create files for each database\n    (and the fact that we haven't provided an option to map filename-safe\n    IDs to arbitrary, user-supplied IndexedDB database names),\n    when the user creates IndexedDB databases, the Node implementation\n    will be subject to the limitations systems can have with filenames.\n    Since IndexedDBShim aims to facilitate code that can work on both\n    the server and client, we have applied some escaping and restrictions\n    by default. The default behavior is to prefix the database name with\n    `D_` (to avoid filesystem, SQLite, and `node-sqlite3` problems if\n    the user supplies the IndexedDB-permitted empty string database\n    name), to escape `^` which we use as our own generally-filename-supported\n    escape character, to escape NUL (which is also problematic in SQLite\n    identifiers and in `node-sqlite3` in general) as `^0`, to escape upper-case\n    letters A-Z as `^A`, `^B`, etc. (since IndexedDB insists on\n    case-sensitivity while file systems often do not), to escape any\n    characters mentioned in `databaseCharacterEscapeList` (as `^1` + a\n    two-hexadecimal-digit-padded sequence), and to throw an `Error` if\n    `databaseNameLengthLimit` is not set to `false` and is surpassed\n    by the resulting escaped name. You can use this `escapeDatabaseName`\n    callback property to override the default behavior, with the callback\n    accepting a single argument of the user's database name choice and\n    returning your own filename-safe value. Note that we do escape NUL and\n    our own escape character (`^`) before passing in the value (for the\n    above-mentioned reasons), though you could unescape and\n    return your own escaped format. While some file systems may not have\n    the other restrictions, you should at a minimum anticipate\n    the possibility for empty strings (since we rely on the result of this\n    function for internal escaping as a SQLite identifier) as well as\n    realize the string `\":memory:\"` will, if unescaped, have a special\n    meaning with `node-sqlite3`. You can make the escaping more lax,\n    e.g., if your file system is case-sensitive, or you could make it more\n    stringent.\n- __unescapeDatabaseName__ - Not used internally; usable as a convenience\n    method for unescaping strings formatted per our default escaping\n    conventions.\n- __databaseCharacterEscapeList__ - When this property and\n    `escapeDatabaseName` are not overridden, the following characters will\n    be escaped by default, even though IndexedDB has no such restrictions,\n    as they are restricted in a number of file systems, even modern,\n    Unicode-supporting ones: `0x00-0x1F 0x7F \" * / : \u003c \u003e ? \\ |`. This\n    property can be overridden with a string that will be converted into\n    an alternate regular expression or supplied with `false` to disable\n    any character limitations.\n- __databaseNameLengthLimit__ - When this property and\n    `escapeDatabaseName` are not overridden, an error will be thrown if\n    the escaped filename exceeds the length of 254 characters (the shortest\n    typical modern file length maximum). Provide a number to change the\n    limit or supply `false` to disable any length checking.\n- __escapeNFDForDatabaseNames__ - Boolean defaulting to true on whether\n    to escape NFD-escaping characters to avoid clashes on MacOS which\n    performs NFD on files\n- __addSQLiteExtension__ - Boolean on whether to add the `.sqlite` extension\n    to database file names (including `__sysdb__` which tracks versions);\n    defaults to `true`\n- __autoName__ - Boolean config to interpret empty string name as a\n    cue for creating a database name automatically (introspect on\n    `IDBDatabase.name` to get the actual name used); `false` by default\n\nNode-only config:\n\n- __sysDatabaseBasePath__ - Base path for the `__sysdb__(.sqlite)` database\n    file; defaults to `__databaseBasePath` unless another value (including\n    the empty string) is given; otherwise is the empty string\n- __databaseBasePath__ - Base path for user database files; defaults to the\n    empty string\n- __deleteDatabaseFiles__ - Deletes physical database file upon\n    `deleteDatabase` (instead of merely emptying). Defaults to `true`.\n    Does not currently delete the database for tracking available\n    databases and versions, `__sys__`, if emptied; see\n    [#278](https://github.com/axemclion/IndexedDBShim/issues/278).\n- __memoryDatabase__ - String config to cause all opening, deleting, and\n    listing to be of SQLite in-memory databases; name supplied\n    by user is still used (including to automatically build a cache since\n    SQLite does not allow naming of in-memory databases); the name is also\n    accessible to `IDBFactory.databases()`; causes database\n    name/version tracking to also be within an in-memory database; if\n    set in the browser, avoids normal database name escaping meant\n    for Node compatibility; allowable values include the empty string,\n    `\":memory:\"`, and `file::memory:[?optionalQueryString][#optionalHash]`.\n    See \u003chttps://sqlite.org/inmemorydb.html\u003e and \u003chttps://sqlite.org/uri.html\u003e\n    for more on the function and form of such values\n\nNode config mostly for development debugging:\n\n- __sqlBusyTimeout__ - Integer used by Node WebSQL for\n    [SQLite config](https://github.com/mapbox/node-sqlite3/wiki/API#databaseconfigureoption-value)\n    to set the [busy timeout](https://www.sqlite.org/c3ref/busy_timeout.html)\n    (Defaults to 1000 ms)\n- __sqlTrace__ - Callback used by Node WebSQL for\n    [SQLite config](https://github.com/mapbox/node-sqlite3/wiki/API#databaseconfigureoption-value)\n    (Invoked when an SQL statement executes, with a rendering of the\n    statement text)\n- __sqlProfile__ - Callback used by Node WebSQL for\n    [SQLite config](https://github.com/mapbox/node-sqlite3/wiki/API#databaseconfigureoption-value)\n    (Invoked every time an SQL statement executes)\n    // Overcoming limitations with node-sqlite3/storing database name on\n    // file systems\n    // https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words\n\n### shimIndexedDB.\\__getConfig()\n\nFor retrieving a config value:\n\n```js\nshimIndexedDB.__getConfig(property);\n```\n\n## Known Issues\n\nAll code has bugs, and this project is no exception.  If you find a bug,\nplease [let us know about it](https://github.com/indexeddbshim/indexeddbshim/issues).\nOr better yet, [send us a fix](https://github.com/indexeddbshim/indexeddbshim/pulls)!\nPlease make sure someone else hasn't already reported the same bug though.\n\nHere is a summary of main [known issues](https://github.com/axemclion/IndexedDBShim/issues/262#issuecomment-254413002)\nto resolve:\n\n1. `blocked` and `versionchange` `IDBVersionChangeEvent` event support ([#2](https://github.com/axemclion/IndexedDBShim/issues/2) and [#273](https://github.com/axemclion/IndexedDBShim/issues/273)) across\nprocesses/browser windows\n1. Some issues related to [task/micro-task timing](https://github.com/axemclion/IndexedDBShim/issues/296)\nin Node (for inherent limitations in the browser, see below).\n1. [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/ImageData) storage on Node 14 when used with `node-canvas` - due to [this issue](https://github.com/Automattic/node-canvas/issues/1646)\n\nThere are a few bugs that are outside of our power to fix.  Namely:\n\n### Browser rollback\n\nWhile we do try to rollback the database version in the browser when\ncalled for, as we are not able to prolong WebSQL transactions to benefit\nfrom the auto-rollback they perform upon encountering an error (nor\ndoes WebSQL permit manual ROLLBACK commands so that we could undo the\nvarious WebSQL calls we need to make up IndexedDB transactions), we are\nnot able to provide safe rollbacks in the browser. The synchronous WebSQL\nAPI was not apparently well supported, at least it is missing in Safari\nand Chrome, and it would particularly degrade performance in a Node\nenvironment.\n\nThe special build of `websql` that we use does allow such\nIndexedDB-spec-compliant (and data-integrity-friendly!) rollback behavior\nin Node.\n\nSee below on task/micro-task timing for more.\n\n### Task/micro-task timing\n\nIndexedDB transactions [will timeout](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB#Adding_data_to_the_database)\nso long as there are no detected active requests.\n\nWhile a single promise delay (a \"microtask\") is not supposed to be\nlong enough to cause a transaction timeout (and they do not in Node\nwhere we have control over extending the transaction), it could possibly\noccur in our browser implementation.\n\n(Note that chaining multiple promises or having a long-resolving\npromise will likely cause a transaction to expire even in compliant\nimplementations.)\n\nA `setTimeout` timeout of `0`, on the other hand (a full \"task\"), ought,\nfor compliant implementations, to be long enough of a time to cause a\ntime out of the transaction, but in Node where we prolong transactions\nlong enough to ensure our full chain of asynchronous SQL needed for the\ntransaction operations is run (as well as ensure complete rollback should\nthere be an error causing a transaction abort), it may be too short.\n\nWe could fix this in Node (where we can have access to a synchronous\nSQLite API such as \u003chttps://github.com/grumdrig/node-sqlite\u003e unlike\non the browser) and ensure transactions finish before the next task\n(though always after a microtask), but as mentioned above, this would\ndegrade performance particularly on a server (and in the browser,\nthe WebSQL API on which we are relying did not apparently\ngain support in browsers for the synchronous API).\n\n[This test](https://github.com/w3c/web-platform-tests/blob/master/IndexedDB/transaction-deactivation-timing.html) and\n[this one](https://github.com/w3c/web-platform-tests/blob/master/IndexedDB/upgrade-transaction-deactivation-timing.html)\ndemonstrate the *expected* timeout behavior with regard to `setTimeout`\nor promises and transaction expiration.\n\n### [Structured Cloning Algorithm](https://html.spec.whatwg.org/multipage/infrastructure.html#safe-passing-of-structured-data)\n\nDue to\n[certain challenges](http://stackoverflow.com/questions/42170826/categories-for-rejection-by-the-structured-cloning-algorithm)\nin detecting cloneable objects from within JavaScript, there are certain\nlimitations regarding cloning:\n\n1. We cannot properly detect `Proxy` to throw upon encountering such\n    non-cloneable objects\n1. Our reliance on `Object.prototype.toString` to detect uncloneable objects\n    can fail if that method is overridden or if `Symbol.toStringTag` is used\n    to change the default reporting of a given \"class\".\n1. Although they are currently working, we were only able to resolve `Blob`,\n    `File`, and `FileList` objects synchronously (as\n    [required per spec](https://github.com/axemclion/IndexedDBShim/issues/285))\n    using the now-deprecated `XMLHttpRequest` synchronous API.\n1. Without a means of transferring `ArrayBuffer` objects in Node, we cannot\n    meet the requirement to fail upon encountering detached binary objects.\n1. They may be other subtleties we have not been able to work around.\n\nWe have, however, overcome some cloning issues still faced by browser\nimplementations, e.g., in Chrome (issue\n[#698564](https://bugs.chromium.org/p/chromium/issues/detail?id=698564))\n(re: not failing on `WeakMap`, `WeakSet`, `Promise`, and `Object.prototype`).\n\nWe also have limitations in creating certain objects synchronously, namely, the\none method for creating an image bitmap, `createImageBitmap`, returns a\n`Promise`, so we cannot clone a bona fide image bitmap synchronously so as to\nobtain any errors synchronously as expected by the IndexedDB methods involving\ncloning.\n\n### Node versions 8.9.3 to 9.0.0\n\nOur Mocha test \"query multi-entry indexes with hundreds of records\" of\n`IDBIndex/openCursor-spec.js` is failing for these versions. Starting\nwith 9.1.0, however, the test passes again.\n\n### iOS\n\nDue to a [bug in WebKit](https://bugs.webkit.org/show_bug.cgi?id=137034), the\n`window.indexedDB` property is read-only and cannot be overridden by\nIndexedDBShim.  There are two possible workarounds for this:\n\n1. Use `window.shimIndexedDB` instead of `window.indexedDB`\n1. Create an `indexedDB` variable in your closure\n\nBy creating a variable named `indexedDB`, all the code within that closure\nwill use the variable instead of the `window.indexedDB` property.  For\nexample:\n\n```js\n(function () {\n    // This works on all browsers, and only uses IndexedDBShim as a final fallback\n    var indexedDB = window.indexedDB || window.mozIndexedDB || // eslint-disable-line no-var -- Older browsers\n        window.webkitIndexedDB || window.msIndexedDB || window.shimIndexedDB;\n\n    // This code will use the native IndexedDB, if it exists, or the shim otherwise\n    indexedDB.open('MyDatabase', 1);\n}());\n```\n\n### Windows Phone\n\n*This information might be outdated. Reports on current support or fixes welcome.*\n\nIndexedDBShim works on Windows Phone via a Cordova/PhoneGap plug-in.  There\nare two plugins available: [cordova-plugin-indexedDB](https://github.com/MSOpenTech/cordova-plugin-indexedDB)\nand [cordova-plugin-indexeddb-async](https://github.com/ABB-Austin/cordova-plugin-indexeddb-async).\nBoth plug-ins rely on a WebSQL-to-SQLite adapter, but there are differences\nin their implementations.  Try them both and see which one works best for\nyour app.\n\n## Building\n\nTo build the project locally on your computer:\n\n1. __Clone this repo__\nIf you clone the repository to work against an unstable version, you only\nneed to clone the repository recursively (via\n`git clone https://github.com/indexeddbshim/indexeddbshim.git --recursive`)\nif you wish to have the W3C tests available for testing (which\nunfortunately loads all W3C tests into the \"web-platform-tests\"\nsubdirectory rather than just the IndexedDB ones). Otherwise, just use\n`git clone https://github.com/indexeddbshim/indexeddbshim.git`\n\n1. __Install dev dependencies (and websql for Node)__\n`yarn install`\n\n1. __Run the build script__\n`npm start`\n\n1. __Done__\n\nThe output files will be generated in the `dist` directory\n\n## Upgrading from previous versions\n\nSee [Versions](docs/versions/) for migration information.\n\n## Testing\n\nSee [TESTING](docs/TESTING.md).\n\n## Resources for IndexedDB\n\n- [TrialTool](http://nparashuram.com/trialtool) - For experimenting with\n    IndexedDB commands, including predefined examples. (Some examples\n    may depend on others previously being run, even with\n    \"Load Pre-Requisites\" added, but it is nevertheless useful to avoid\n    boilerplate in testing out commands, in conjunction with\n    the browser developer tools.)\n\n## Contributing\n\nPull requests or Bug reports welcome! See [CONTRIBUTING](docs/CONTRIBUTING.MD)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexeddbshim%2Findexeddbshim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findexeddbshim%2Findexeddbshim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexeddbshim%2Findexeddbshim/lists"}