{"id":19005178,"url":"https://github.com/dhis2/app-service-datastore","last_synced_at":"2025-06-11T11:38:39.658Z","repository":{"id":52203785,"uuid":"255653677","full_name":"dhis2/app-service-datastore","owner":"dhis2","description":"Persistent settings and saved objects for DHIS2 Platform applications","archived":false,"fork":false,"pushed_at":"2023-03-25T07:47:53.000Z","size":249,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-06-01T02:55:39.560Z","etag":null,"topics":["hacktoberfest","hacktoberfest2022","synced-settings","web-lib"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/dhis2.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-14T15:51:36.000Z","updated_at":"2022-10-05T17:37:48.000Z","dependencies_parsed_at":"2024-11-08T18:31:41.122Z","dependency_job_id":"1f8115b1-9a37-4c71-9788-afd429952b60","html_url":"https://github.com/dhis2/app-service-datastore","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fapp-service-datastore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fapp-service-datastore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fapp-service-datastore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fapp-service-datastore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhis2","download_url":"https://codeload.github.com/dhis2/app-service-datastore/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fapp-service-datastore/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259256440,"owners_count":22829630,"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":["hacktoberfest","hacktoberfest2022","synced-settings","web-lib"],"created_at":"2024-11-08T18:26:31.592Z","updated_at":"2025-06-11T11:38:39.626Z","avatar_url":"https://github.com/dhis2.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DataStore App Service\n\n\u003e **WARNING**: THIS SERVICE IS STILL A WORK-IN-PROGRESS, THE API WILL PROBABLY CHANGE!\n\nThis DataStore app service support persistent user and global application settings as well as saved (and sharable) objects, such as visualization configurations.\n\nThis library was bootstrapped with [DHIS2 Application Platform](https://github.com/dhis2/app-platform).\n\n## Installation\n\n```sh\nyarn add @dhis2/app-service-datastore\n```\n\n## Features\n\n- Save and load application settings from a well-known dataStore (or userDataStore) key\n- Create, read, update, and delete saved objects (i.e. `visualizations`) from a managed key-value store in the dataStore or userDataStore\n- Client-side syncronized state - automatically re-render all components which use a setting or object when that setting or object is updated somewhere else in the application (no refetch required)\n- Optimistic updates - propagate \"provisional\" data to all consumers while mutation is in-transit, roll back changes if the mutation fails\n- Optionally encrypt settings data at rest\n\n## API\n\n### DataStoreProvider props\n\n| **Name**              | **Type**          | **Required** | **Default** | **Description**                                                                  |\n| --------------------- | ----------------- | ------------ | ----------- | -------------------------------------------------------------------------------- |\n| namespace             | _Boolean_         | **REQUIRED** |             | The namespace to use                                                             |\n| loadingComponent      | _React Component_ |              | null        | A component to render during initial load                                        |\n| defaultGlobalSettings | _Object_          |              | {}          | Default settings to save in the dataStore                                        |\n| defaultUserSettings   | _Object_          |              | {}          | Default settings to save in the userDataStore                                    |\n| encryptSettings       | _boolean_         |              | false       | If true, encrypt all settings at rest (important if credentials could be stored) |\n\n### Hooks\n\nThis library provides four main hooks:\n\n```ts\ntype useSetting = (\n  id: string,\n  options?: HookOptions\n) =\u003e [value: any, { set: (newValue: any) =\u003e Promise\u003cvoid\u003e }];\n\ntype useAllSettings = (\n  options?: HookOptions\n) =\u003e [\n  settings: Record\u003cstring, any\u003e,\n  { set: (key: string, value: any) =\u003e Promise\u003cvoid\u003e }\n];\n\ntype useSavedObject = (\n  id: string,\n  options?: HookOptions\n) =\u003e [\n  obj: object,\n  {\n    update: (obj: object) =\u003e Promise\u003cobject\u003e;\n    replace: (obj: object) =\u003e Promise\u003cvoid\u003e;\n    remove: () =\u003e Promise\u003cvoid\u003e;\n  }\n];\n\ntype useSavedObjectList = (\n  options?: HookOptions\n) =\u003e [\n  list: object[],\n  {\n    add: (obj: object) =\u003e Promise\u003cvoid\u003e;\n    update: (id: string, obj: object) =\u003e Promise\u003cobject\u003e;\n    replace: (id: string, obj: object) =\u003e Promise\u003cvoid\u003e;\n    remove: (id: string) =\u003e Promise\u003cvoid\u003e;\n  }\n];\n```\n\nEach of the hooks accepts an optional options object:\n\n```ts\ntype HookOptions = {\n  // If true, store this setting or object in the dataStore instead of userDataStore\n  global: boolean;\n\n  // If true, do NOT rerender this component when the value is changed somewhere else in the application\n  ignoreUpdates: boolean;\n};\n```\n\nThere is one additional hook which exposes the DataStore controller for imperative access (advanced):\n\n```ts\ntype useDataStore = () =\u003e DataStore;\n```\n\n## Usage\n\n### Wrap the application in a DataStore provider\n\n```jsx\nimport React from \"react\";\nimport { DataStoreProvider } from \"@dhis2/app-service-datastore\";\nimport AppRouter from \"./AppRouter\";\n\nconst App = () =\u003e (\n  \u003cDataStoreProvider namespace=\"myAppName\"\u003e\n    \u003cAppRouter /\u003e\n  \u003c/DataStoreProvider\u003e\n);\n\nexport default App;\n```\n\n### Reading settings\n\n```jsx\nimport React from \"react\";\nimport { useSetting, useAllSettings } from \"@dhis2/app-service-datastore\";\n\nconst MyComponent = () =\u003e {\n  // All data-store settings for the current user\n  const [allUserSettings] = useAllSettings();\n  // All data-store settings within the namespace\n  const [allGlobalSettings] = useAllSettings({ global: true });\n  // A specific setting for the current user\n  const [aUserSetting] = useSetting(\"id-1\");\n  // A specific global setting\n  const [aGlobalSetting] = useSetting(\"id-1\", { global: true });\n\n  return \"Something\";\n};\n\nexport default MyComponent;\n```\n\n### Reading saved objects\n\n```jsx\nimport React from \"react\";\nimport {\n  useSavedObject,\n  useSavedObjectList,\n} from \"@dhis2/app-service-datastore\";\n\nconst MyComponent = () =\u003e {\n  // All saved objects for the current user\n  const [allUserSavedObjects] = useSavedObjectList();\n  // All saved objects within the namespace\n  const [allGlobalSavedObjects] = useSavedObjectList({ global: true });\n  // A specific saved object for the current user\n  const [aUserSavedObject] = useSavedObject(\"id-1\");\n  // A specific global saved object\n  const [aGlobalSavedObject] = useSavedObject(\"id-1\", { global: true });\n\n  return \"Something\";\n};\n\nexport default MyComponent;\n```\n\n### Mutating settings and saved objects\n\n```jsx\nimport React from \"react\";\nimport {\n  useSavedObject,\n  useSavedObjectList,\n  useSetting,\n  useAllSettings,\n} from \"@dhis2/app-service-datastore\";\n\nconst MyComponent = () =\u003e {\n  // A setting for the current user\n  const [userSetting, { set }] = useSetting(\"id-1\");\n\n  // All settings for the current user\n  const [userSettings, { set }] = useAllSettings();\n\n  // A saved object for the current user\n  const [savedObject, { update, replace, remove }] = useSavedObject(\"id-1\");\n\n  // All saved objects for the current user\n  const [\n    allUserSavedObjects,\n    { add, update, replace, remove },\n  ] = useSavedObjectList();\n\n  return \"Something\";\n};\n```\n\n## Report an issue\n\nThe issue tracker can be found in [DHIS2 JIRA](https://jira.dhis2.org)\nunder the [LIBS](https://jira.dhis2.org/projects/LIBS) project.\n\nDeep links:\n\n- [Bug](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10006\u0026components=11027)\n- [Feature](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10300\u0026components=11027)\n- [Task](https://jira.dhis2.org/secure/CreateIssueDetails!init.jspa?pid=10700\u0026issuetype=10003\u0026components=11027)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fapp-service-datastore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhis2%2Fapp-service-datastore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fapp-service-datastore/lists"}