{"id":13447437,"url":"https://github.com/knadh/localStorageDB","last_synced_at":"2025-03-22T01:30:59.948Z","repository":{"id":1690834,"uuid":"2418932","full_name":"knadh/localStorageDB","owner":"knadh","description":"A simple database layer for localStorage and sessionStorage for creating structured data in the form of databases and tables","archived":false,"fork":false,"pushed_at":"2023-11-08T11:03:56.000Z","size":135,"stargazers_count":802,"open_issues_count":4,"forks_count":128,"subscribers_count":37,"default_branch":"master","last_synced_at":"2024-04-17T02:49:01.149Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://nadh.in/code/localstoragedb","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/knadh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":null,"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}},"created_at":"2011-09-19T22:55:03.000Z","updated_at":"2024-06-18T15:23:55.791Z","dependencies_parsed_at":"2024-06-18T15:23:54.064Z","dependency_job_id":"221c30a6-ca2a-43ad-959d-62f9c8239bd2","html_url":"https://github.com/knadh/localStorageDB","commit_stats":{"total_commits":92,"total_committers":19,"mean_commits":4.842105263157895,"dds":"0.32608695652173914","last_synced_commit":"c0eb1e8c1e72fd6943cc8b898750a9a20a2f511c"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2FlocalStorageDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2FlocalStorageDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2FlocalStorageDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knadh%2FlocalStorageDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knadh","download_url":"https://codeload.github.com/knadh/localStorageDB/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244075615,"owners_count":20393979,"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-07-31T05:01:17.668Z","updated_at":"2025-03-22T01:30:59.654Z","avatar_url":"https://github.com/knadh.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# localStorageDB 2.3.2\nlocalStorageDB is a simple layer over localStorage (and sessionStorage) that provides\na set of functions to store structured data like databases and tables.\nIt provides basic insert/update/delete/query capabilities.\nlocalStorageDB has no dependencies, and is not based on WebSQL. Underneath it all,\nthe structured data is stored as serialized JSON in localStorage or sessionStorage.\n\n- Kailash Nadh\n- v 2.3.2 Mar 2018 Contribution: Ken Kohler\n- v 2.3.1 Mar 2015\n- v 2.3.0 Feb 2014 Contribution: Christian Kellner (http://orange-coding.net)\n- v 2.2 Jan 2014 Contribution: Andy Hawkins (http://a904guy.com)\n- v 2.1 Nov 2013\n- v 2.0 Jun 2013\n- v 1.9 Nov 2012\n- Documentation: [http://nadh.in/code/localstoragedb](http://nadh.in/code/localstoragedb)\n- Licensed: MIT license\n\n# Installation\n\n## NPM\n`npm install localstoragedb`\n\n## Yarn\n`yarn add localstoragedb`\n\n## Bower\n`bower install localstoragedb`\n\n\n# Run Test Cases\n\n```shell\nbower install # install mocha and chai for running test cases\n```\n`open test/local_storage_db_test.html in Browser to check the result`\n\n# Supported Browsers\nBrowsers need to support \"Local Storage\" in order to make localeStorageDB working.\n\n- IE 8\u003c\n- Firefox 31\u003c\n- Chrome 31\u003c\n- Safari 7\u003c\n- iOS Safari 7.1\u003c\n- Android Browser 4.1\u003c\n- Chrome for Android 42\u003c\n\n# Usage / Examples\n### Creating a database, table, and populating the table\n\n```javascript\n// Initialise. If the database doesn't exist, it is created\nvar lib = new localStorageDB(\"library\", localStorage);\n\n// Check if the database was just created. Useful for initial database setup\nif( lib.isNew() ) {\n\n    // create the \"books\" table\n\tlib.createTable(\"books\", [\"code\", \"title\", \"author\", \"year\", \"copies\"]);\n\n\t// insert some data\n\tlib.insert(\"books\", {code: \"B001\", title: \"Phantoms in the brain\", author: \"Ramachandran\", year: 1999, copies: 10});\n\tlib.insert(\"books\", {code: \"B002\", title: \"The tell-tale brain\", author: \"Ramachandran\", year: 2011, copies: 10});\n\tlib.insert(\"books\", {code: \"B003\", title: \"Freakonomics\", author: \"Levitt and Dubner\", year: 2005, copies: 10});\n\tlib.insert(\"books\", {code: \"B004\", title: \"Predictably irrational\", author: \"Ariely\", year: 2008, copies: 10});\n\tlib.insert(\"books\", {code: \"B005\", title: \"Tesla: Man out of time\", author: \"Cheney\", year: 2001, copies: 10});\n\tlib.insert(\"books\", {code: \"B006\", title: \"Salmon fishing in the Yemen\", author: \"Torday\", year: 2007, copies: 10});\n\tlib.insert(\"books\", {code: \"B007\", title: \"The user illusion\", author: \"Norretranders\", year: 1999, copies: 10});\n\tlib.insert(\"books\", {code: \"B008\", title: \"Hubble: Window of the universe\", author: \"Sparrow\", year: 2010, copies: 10});\n\n\t// commit the database to localStorage\n\t// all create/drop/insert/update/delete operations should be committed\n\tlib.commit();\n}\n```\n\n### Creating and populating a table in one go\n```javascript\n\t// rows for pre-population\n\tvar rows = [\n\t\t{code: \"B001\", title: \"Phantoms in the brain\", author: \"Ramachandran\", year: 1999, copies: 10},\n\t\t{code: \"B002\", title: \"The tell-tale brain\", author: \"Ramachandran\", year: 2011, copies: 10},\n\t\t{code: \"B003\", title: \"Freakonomics\", author: \"Levitt and Dubner\", year: 2005, copies: 10},\n\t\t{code: \"B004\", title: \"Predictably irrational\", author: \"Ariely\", year: 2008, copies: 10},\n\t\t{code: \"B005\", title: \"Tesla: Man out of time\", author: \"Cheney\", year: 2001, copies: 10},\n\t\t{code: \"B006\", title: \"Salmon fishing in the Yemen\", author: \"Torday\", year: 2007, copies: 10},\n\t\t{code: \"B007\", title: \"The user illusion\", author: \"Norretranders\", year: 1999, copies: 10},\n\t\t{code: \"B008\", title: \"Hubble: Window of the universe\", author: \"Sparrow\", year: 2010, copies: 10}\n\t];\n\n\t// create the table and insert records in one go\n\tlib.createTableWithData(\"books\", rows);\n\n\tlib.commit();\n```\n### Altering\n```javascript\n// If database already exists, and want to alter existing tables\nif(! (lib.columnExists(\"books\", \"publication\")) ) {\n\tlib.alterTable(\"books\", \"publication\", \"McGraw-Hill Education\");\n\tlib.commit(); // commit the deletions to localStorage\n}\n\n// Multiple columns can also added at once\nif(! (lib.columnExists(\"books\", \"publication\") \u0026\u0026 lib.columnExists(\"books\", \"ISBN\")) ) {\n\tlib.alterTable(\"books\", [\"publication\", \"ISBN\"], {publication: \"McGraw-Hill Education\", ISBN: \"85-359-0277-5\"});\n\tlib.commit(); // commit the deletions to localStorage\n}\n```\n\n### Querying\n`query()` is deprecated. Use `queryAll()` instead.\n\n```javascript\n// simple select queries\nlib.queryAll(\"books\", {\n\tquery: {year: 2011}\n});\nlib.queryAll(\"books\", {\n\tquery: {year: 1999, author: \"Norretranders\"}\n});\n\n// select all books\nlib.queryAll(\"books\");\n\n// select all books published after 2003\nlib.queryAll(\"books\", {\n\tquery: function(row) {    // the callback function is applied to every row in the table\n\t\tif(row.year \u003e 2003) {\t\t// if it returns true, the row is selected\n\t\t\treturn true;\n\t\t} else {\n\t\t\treturn false;\n\t\t}\n\t}\n});\n\n// select all books by Torday and Sparrow\nlib.queryAll(\"books\", {\n    query: function(row) {\n            if(row.author == \"Torday\" || row.author == \"Sparrow\") {\n\t\t        return true;\n\t        } else {\n\t\t        return false;\n\t    }\n    },\n    limit: 5\n});\n```\n\n### Sorting\n```javascript\n// select 5 rows sorted in ascending order by author\nlib.queryAll(\"books\", { limit: 5,\n                        sort: [[\"author\", \"ASC\"]]\n                      });\n\n// select all rows first sorted in ascending order by author, and then, in descending, by year\nlib.queryAll(\"books\", { sort: [[\"author\", \"ASC\"], [\"year\", \"DESC\"]] });\n\nlib.queryAll(\"books\", { query: {\"year\": 2011},\n                        limit: 5,\n                        sort: [[\"author\", \"ASC\"]]\n                      });\n\n// or using query()'s positional arguments, which is a little messy (DEPRECATED)\nlib.query(\"books\", null, null, null, [[\"author\", \"ASC\"]]);\n```\n\n### Distinct records\n```javascript\nlib.queryAll(\"books\", { distinct: [\"year\", \"author\"]\n                      });\n\n```\n\n### Example results from a query\n```javascript\n// query results are returned as arrays of object literals\n// an ID field with the internal auto-incremented id of the row is also included\n// thus, ID is a reserved field name\n\nlib.queryAll(\"books\", {query: {author: \"ramachandran\"}});\n\n/* results\n[\n {\n   ID: 1,\n   code: \"B001\",\n   title: \"Phantoms in the brain\",\n   author: \"Ramachandran\",\n   year: 1999,\n   copies: 10\n },\n {\n   ID: 2,\n   code: \"B002\",\n   title: \"The tell-tale brain\",\n   author: \"Ramachandran\",\n   year: 2011,\n   copies: 10\n }\n]\n*/\n```\n\n\n### Updating\n```javascript\n// change the title of books published in 1999 to \"Unknown\"\nlib.update(\"books\", {year: 1999}, function(row) {\n\trow.title = \"Unknown\";\n\n\t// the update callback function returns to the modified record\n\treturn row;\n});\n\n// add +5 copies to all books published after 2003\nlib.update(\"books\",\n\tfunction(row) {\t// select condition callback\n\t\tif(row.year \u003e 2003) {\n\t\t\treturn true;\n\t\t} else {\n\t\t\treturn false;\n\t\t}\n\t},\n\tfunction(row) { // update function\n\t\trow.copies+=5;\n\t\treturn row;\n\t}\n);\n```\n\n### Insert or Update conditionally\n```javascript\n// if there's a book with code B003, update it, or insert it as a new row\nlib.insertOrUpdate(\"books\", {code: 'B003'}, {\tcode: \"B003\",\n\t\t\t\t\t\ttitle: \"Freakonomics\",\n\t\t\t\t\t\tauthor: \"Levitt and Dubner\",\n\t\t\t\t\t\tyear: 2005,\n\t\t\t\t\t\tcopies: 15});\n\nlib.commit();\n```\n\n### Deleting\n```javascript\n// delete all books published in 1999\nlib.deleteRows(\"books\", {year: 1999});\n\n// delete all books published before 2005\nlib.deleteRows(\"books\", function(row) {\n\tif(row.year \u003c 2005) {\n\t\treturn true;\n\t} else {\n\t\treturn false;\n\t}\n});\n\nlib.commit(); // commit the deletions to localStorage\n```\n\n\n# Methods\n\u003ctable\u003e\n\t\u003cthead\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003cth\u003eMethod\u003c/th/\u003e\n\t\t\t\u003cth\u003eArguments\u003c/th/\u003e\n\t\t\t\u003cth\u003eDescription\u003c/th\u003e\n\t\t\u003c/tr\u003e\n\t\u003c/thead\u003e\n\t\u003ctbody\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003elocalStorageDB()\u003c/td\u003e\n\t\t\t\u003ctd\u003edatabase_name, storage_engine\u003c/td\u003e\n\t\t\t\u003ctd\u003eConstructor\u003cbr /\u003e\n\t\t\t\t- storage_engine can either be localStorage (default) or sessionStorage\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003eisNew()\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\t\u003ctd\u003eReturns true if a database was created at the time of initialisation with the constructor\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003edrop()\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\t\u003ctd\u003eDeletes a database, and purges it from localStorage\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003etableCount()\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\t\u003ctd\u003eReturns the number of tables in a database\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003ecommit()\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\t\u003ctd\u003eCommits the database to localStorage. Returns true if successful, and false otherwise (highly unlikely)\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003eserialize()\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\t\u003ctd\u003eReturns the entire database as serialized JSON\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003etableExists()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eChecks whether a table exists in the database\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003etableFields()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eReturns the list of fields of a table\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003ecreateTable()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, fields\u003c/td\u003e\n\t\t\t\u003ctd\u003eCreates a table\u003cbr /\u003e\n\t\t\t\t- fields is an array of string fieldnames. 'ID' is a reserved fieldname.\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003ecreateTableWithData()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, rows\u003c/td\u003e\n\t\t\t\u003ctd\u003eCreates a table and populates it\u003cbr /\u003e\n\t\t\t\t- rows is an array of object literals where each object represents a record\u003cbr /\u003e\n\t\t\t\t[{field1: val, field2: val}, {field1: val, field2: val}]\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003ealterTable()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, new_fields, default_values\u003c/td\u003e\n\t\t\t\u003ctd\u003eAlter a table\u003cbr /\u003e\n\t\t\t\t- new_fields can be a array of columns OR a string of single column.\u003cbr /\u003e\n\t\t\t\t- default_values (optional) can be a object of column's default values OR a default value string for single column for existing rows.\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003edropTable()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eDeletes a table from the database\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003etruncate()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eEmpties all records in a table and resets the internal auto increment ID to 0\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003ecolumnExists()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, field_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eChecks whether a column exists in database table.\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003erowCount()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name\u003c/td\u003e\n\t\t\t\u003ctd\u003eReturns the number of rows in a table\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003einsert()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, data\u003c/td\u003e\n\t\t\t\u003ctd\u003eInserts a row into a table and returns its numerical ID\u003cbr /\u003e\n\t\t\t\t- data is an object literal with field-values\u003cbr /\u003e\n\t\t\t\tEvery row is assigned an auto-incremented numerical ID automatically\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n    \t\u003ctr\u003e\n\t\t\t\u003ctd\u003equery() DEPRECATED\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, query, limit, start, sort\u003c/td\u003e\n\t\t\t\u003ctd\u003e\u003c/td\u003e\n\t\t\u003c/tr\u003e\n        \u003ctr\u003e\n\t\t\t\u003ctd\u003equeryAll()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, params{}\u003c/td\u003e\n\t\t\t\u003ctd\u003e\n\t\t\t\tReturns an array of rows (object literals) from a table matching the query.\u003cbr /\u003e\n\t\t\t\t- query is either an object literal or null. If query is not supplied, all rows are returned\u003cbr /\u003e\n\t\t\t\t- limit is the maximum number of rows to be returned\u003cbr /\u003e\n    \t\t\t- start is the  number of rows to be skipped from the beginning (offset)\u003cbr /\u003e\n    \t\t\t- sort is an array of sort conditions, each one of which is an array in itself with two values\u003cbr /\u003e\n    \t\t\t- distinct is an array of fields whose values have to be unique in the returned rows\u003cbr /\u003e\n\t\t\t\tEvery returned row will have it's internal auto-incremented id assigned to the variable ID\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003eupdate()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, query, update_function\u003c/td\u003e\n\t\t\t\u003ctd\u003eUpdates existing records in a table matching query, and returns the number of rows affected\u003cbr /\u003e\n\t\t\t\t- query is an object literal or a function. If query is not supplied, all rows are updated\u003cbr /\u003e\n\t\t\t\t- update_function is a function that returns an object literal with the updated values\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\t\t\u003ctr\u003e\n\t\t\t\t\u003ctd\u003einsertOrUpdate()\u003c/td\u003e\n\t\t\t\t\u003ctd\u003etable_name, query, data\u003c/td\u003e\n\t\t\t\t\u003ctd\u003eInserts a row into a table if the given query matches no results, or updates the rows matching the query.\u003cbr /\u003e\n\t\t\t\t\t- query is either an object literal, function, or null.\u003cbr /\u003e\n\t\t\t\t\t- data is an object literal with field-values\n\t\t\t\t\t\u003cbr /\u003e\u003cbr /\u003e\n\t\t\t\t\tReturns the numerical ID if a new row was inserted, or an array of IDs if rows were updated\n\t\t\t\t\u003c/td\u003e\n\t\t\t\u003c/tr\u003e\n\t\t\u003ctr\u003e\n\t\t\t\u003ctd\u003edeleteRows()\u003c/td\u003e\n\t\t\t\u003ctd\u003etable_name, query\u003c/td\u003e\n\t\t\t\u003ctd\u003eDeletes rows from a table matching query, and returns the number of rows deleted\u003cbr /\u003e\n\t\t\t\t- query is either an object literal or a function. If query is not supplied, all rows are deleted\n\t\t\t\u003c/td\u003e\n\t\t\u003c/tr\u003e\n\t\u003c/tbody\u003e\n\u003c/table\u003e\n\n# Storing complex objects\nWhile the library is meant for storing fundamental types (strings, numbers, bools), it is possible to store object literals and arrays as column values, with certain caveats. Some comparison queries, distinct etc. may not work. In addition, if you retrieve a stored array in a query result and modify its values in place, these changes will persist throughout further queries until the page is refreshed. This is because localStorageDB loads and unserializes data and keeps it in memory in a global pool until the page is refreshed, and arrays and objects returned in results are passed by reference.\n\nIf you really need to store arrays and objects, you should implement a deep-copy function through which you pass the results before manipulation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknadh%2FlocalStorageDB","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknadh%2FlocalStorageDB","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknadh%2FlocalStorageDB/lists"}