{"id":18314382,"url":"https://github.com/iamrecursion/obsidian-pkvs","last_synced_at":"2025-04-05T19:34:35.544Z","repository":{"id":215168435,"uuid":"738182810","full_name":"iamrecursion/obsidian-pkvs","owner":"iamrecursion","description":"A persistent key-value store for use in Obsidian scripting.","archived":false,"fork":false,"pushed_at":"2024-04-02T23:58:01.000Z","size":73,"stargazers_count":18,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-03T21:33:55.541Z","etag":null,"topics":["javascript","javascript-library","obsidian","obsidian-plugin"],"latest_commit_sha":null,"homepage":"https://github.com/iamrecursion","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamrecursion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2024-01-02T16:14:15.000Z","updated_at":"2025-02-04T13:09:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"e8cb7ce0-04c1-4c7b-a513-87cabee7e673","html_url":"https://github.com/iamrecursion/obsidian-pkvs","commit_stats":null,"previous_names":["iamrecursion/obsidian-pkvs"],"tags_count":6,"template":false,"template_full_name":"obsidianmd/obsidian-sample-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamrecursion%2Fobsidian-pkvs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamrecursion%2Fobsidian-pkvs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamrecursion%2Fobsidian-pkvs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamrecursion%2Fobsidian-pkvs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamrecursion","download_url":"https://codeload.github.com/iamrecursion/obsidian-pkvs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393384,"owners_count":20931806,"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":["javascript","javascript-library","obsidian","obsidian-plugin"],"created_at":"2024-11-05T16:32:34.859Z","updated_at":"2025-04-05T19:34:35.537Z","avatar_url":"https://github.com/iamrecursion.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Persistent Key-Value Store for Obsidian\n\nThis plugin provides a persistent key-value store for use inside scripts in Obsidian, as well as a\nportable [web inspector](#web-inspector) to aid in debugging. This means that you can persist data\nbetween runs of [Templater](https://github.com/SilentVoid13/Templater) templates or\n[Dataview](https://github.com/blacksmithgu/obsidian-dataview) (or\n[Datacore](https://github.com/blacksmithgu/datacore)) queries. Not only that, but you can also\npersist data across sync services that sync the plugin's `data.json`; this means persistence of\nsaved state between devices using the same vault.\n\nNote that this plugin uses `eval` under the hood in combination with\n[serialize-javascript](https://github.com/yahoo/serialize-javascript) to allow for serialization of\nrich JS objects. You must **never store or load untrusted data**, and **usage of this plugin is at\nyour own risk**.\n\n## Usage\n\nThis plugin is intended to be used from _other plugins_ (such as those mentioned above) that allow\nyou to execute JavaScript code in the Obsidian JS virtual machine. It is not intended to be\nuser-facing or provide a non-code interface outside of its settings. If you are not familiar with\nJavaScript, or its use to script Obsidian, this plugin is **not for you**.\n\n### Interface\n\nThe data store is made available to you in the window scope under the name `window.pkvs` (implicitly\naccessible as `pkvs`). The operations available to you are given by the following interface.\n\n```ts\n// The user-facing interface to the persistent key-value store.\ninterface PKVS {\n  // Loads the value at `key` in the persistent data, returning the value if it exists or\n  // `undefined` otherwise.\n  async load(key: PropertyKey): Promise\u003cany\u003e;\n\n  // Stores the provided `value` at the provided `key` in the data store, returning the previous\n  // value at that `key` if it was previously written, or `undefined` otherwise.\n  //\n  // If eager persistence is on, this will write the changes to disk before returning.\n  async store(key: PropertyKey, value: any): Promise\u003cany\u003e;\n\n  // Deletes any value at the provided `key`, returning the previous value if `key` was previously\n  // written, or `undefined` otherwise.\n  //\n  // If eager persistence is on, this will write the changes to disk before returning.\n  async delete(key: PropertyKey): Promise\u003cany\u003e;\n\n  // Returns `true` if `key` exists in the data store, or `false` otherwise.\n  async exists(key: PropertyKey): Promise\u003cboolean\u003e;\n\n  // Forces any in-memory changes to the data store to be written to disk. Once it has returned, the\n  // on-disk state and in-memory state are guaranteed to be the same.\n  async persist(): Promise\u003cvoid\u003e;\n\n  // Sets the store to use lazy persistence regardless of the option in settings.\n  setLazyPersistance(): void;\n\n  // Sets the store to use eager persistence regardless of the option in settings.\n  setEagerPersistence(): void;\n\n  // Sets the store to persist as specified by the option in settings.\n  disablePersistenceOverride(): void;\n```\n\n## Web Inspector\n\nSometimes it is useful to be able to evaluate JavaScript to access this persistent store without\nhaving to write a DVJS query or Templater template. To that end, this plugin includes the\n[Eruda](https://github.com/liriliri/eruda) portable web-inspector front-end.\n\nWhen opening the inspector (using the command palette), you will see the console by default. In\nsettings, you can enable additional tabs, such as a DOM tree, network request and resource\nmonitoring, sources viewing, performance and timing graphs, and so on. Please see the settings\nthemselves for descriptions of what each tab gives you.\n\nThis function is useful for general development, not just interacting with the persistent store.\n\n## Performance\n\nIf you are writing and reading lots of data or large data at once, you may want to enable the \"Lazy\nPersistence\" option in settings. This will only persist data to disk at app-close on a best-effort\nbasis, and instead requires you to manually persist. You can also enable this option\n_programmatically_ by calling `setLazyPersistance` and `setEagerPersistence` as shown above. These\nwill not change the setting for the plugin, but only the currently active behavior.\n\nManual persistence can be performed by calling `persist` above and awaiting on the result to return\nto guarantee writing is complete, or running the \"Persist Data\" command from the command palette.\n\n\u003e ### WARNING\n\u003e\n\u003e Please note that use of lazy persistence **may incur data loss** if you do not persist before\n\u003e closing Obsidian. This is particularly relevant on mobile, where the app may be killed in the\n\u003e background at any time.\n\n## Installation\n\nYou can install the plugin using the following two installation methods.\n\n### Community Plugins\n\n1. Go to Settings and select the Community Plugins tab.\n2. Open the Browse view, and search for \"Persistent Key-Value Store\".\n3. Select this plugin, and press \"Install\" and then \"Enable\".\n4. It should now work!\n\n### BRAT\n\n1. Install [BRAT](https://github.com/TfTHacker/obsidian42-brat).\n2. In BRAT settings, select \"Add Beta Plugin\" and paste\n   `https://github.com/iamrecursion/obsidian-pkvs` as the URL.\n3. Go to the \"Community Plugins\" tab and enable the plugin.\n\n## Contributing\n\nIf you are interested in contributing code, documentation, or ideas to this project, please take a\nlook at the [CONTRIBUTING](./CONTRIBUTING.md) guide.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamrecursion%2Fobsidian-pkvs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamrecursion%2Fobsidian-pkvs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamrecursion%2Fobsidian-pkvs/lists"}