{"id":22221913,"url":"https://github.com/fabiospampinato/configuration","last_synced_at":"2025-07-06T02:40:02.776Z","repository":{"id":57205495,"uuid":"213263449","full_name":"fabiospampinato/configuration","owner":"fabiospampinato","description":"Performant and feature rich library for managing configurations/settings.","archived":false,"fork":false,"pushed_at":"2023-10-14T17:59:56.000Z","size":116,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-30T11:46:08.181Z","etag":null,"topics":["configuration","managment","performant","preferences","settings"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/fabiospampinato.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"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},"funding":{"github":"fabiospampinato","custom":"https://www.paypal.me/fabiospampinato"}},"created_at":"2019-10-07T00:08:10.000Z","updated_at":"2024-06-26T20:40:18.000Z","dependencies_parsed_at":"2023-01-23T17:31:12.339Z","dependency_job_id":"af4797cb-f1d2-40ce-b9a0-0d10608e1f98","html_url":"https://github.com/fabiospampinato/configuration","commit_stats":{"total_commits":73,"total_committers":2,"mean_commits":36.5,"dds":"0.013698630136986356","last_synced_commit":"f32bc02338b1103cd083ff3cfb560f615bb13cdd"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fconfiguration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fconfiguration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fconfiguration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fconfiguration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiospampinato","download_url":"https://codeload.github.com/fabiospampinato/configuration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817017,"owners_count":17824200,"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":["configuration","managment","performant","preferences","settings"],"created_at":"2024-12-02T23:16:09.387Z","updated_at":"2024-12-02T23:16:10.053Z","avatar_url":"https://github.com/fabiospampinato.png","language":"JavaScript","funding_links":["https://github.com/sponsors/fabiospampinato","https://www.paypal.me/fabiospampinato"],"categories":[],"sub_categories":[],"readme":"# Configuration\n\nPerformant and feature rich library for managing configurations/settings.\n\n## Features\n\nThis library has been modeled after VSCode's settings system, and it can be used for implementing a similarly powerful system in your app.\n\n- **Performant**: it's designed to be extremely fast.\n- **Providers**: a provider reads and writes the actual data, many are built-in (memory, json, local storage etc.) and others can be written easily.\n- **Universal**: it works in the browser too, just use a suitable provider.\n- **Scopes**: a single configuration instance can have multiple providers, so for example a `global + local` setup can be implemented easily.\n- **Filtering**: an arbitrary filter function can be provided, for example to make sure the settings are filtered by a schema.\n- **Path props**: path props (e.g. `foo.bar`) are supported for retrieving/setting/deleting entries.\n- **Flat objects**: flat objects (e.g. `{ 'foo.bar': true, 'foo.baz': false }`) are supported transparently too.\n\n## Install\n\n```sh\nnpm install --save configuration\n```\n\n## Usage\n\nThe following providers are built-in:\n\n```ts\nimport ProviderAbstract from 'configuration/abstract'; // The most basic abstract provider\nimport ProviderAbstractFile from 'configuration/abstract-file'; // The most basic abstract file provider\nimport ProviderAbstractJSON from 'configuration/abstract-json'; // The most basic abstract JSON-backed file provider\nimport ProviderFile from 'configuration/file'; // A provider that reads/writes to a file\nimport ProviderJSON from 'configuration/json'; // A provider that reads/writes to a JSON file\nimport ProviderMemory from 'configuration/memory'; // A provider that reads/writes to memory\nimport ProviderStorage from 'configuration/storage'; // A provider that reads/writes to a general web storage object\nimport ProviderLocalStorage from 'configuration/local-storage'; // A provider that reads/writes to localStorage\nimport ProviderSessionStorage from 'configuration/session-storage'; // A provider that reads/writes to sessionStorage\n```\n\nThis is how you'd create a multi-tier settings sytem:\n\n```ts\nimport Configuration from 'configuration';\nimport ProviderMemory from 'configuration/memory';\nimport ProviderJSON from 'configuration/json';\n\n// Let's initiate the configuration instance\n\nconst Window = new ProviderMemory ({ // A window-level tier, that overrides every other tier\n  scope: 'window', // The name of the scope for this provider\n  defaults: {}, // The default settings object for this provider\n  defaultsRaw: '{\\n\\t// Write window-level settings here\\n}' // The default settings object for this provider as a string\n});\n\nconst Local = new ProviderJSON ({ // A local-level tier, that overrides every other tier except for \"window\"\n  scope: 'local', // The name of the scope for this provider\n  path: './myapp/local.json', // Path where to persist data\n  watching: true, // Whether to watch the file for changes too or not\n  defaults: {}, // The default settings object for this provider\n  defaultsRaw: '{\\n\\t// Write local-level settings here\\n}' // The default settings object for this provider as a string\n});\n\nconst Global = new ProviderJSON ({ // A global-level tier, that overrides only the \"defaults\" tier\n  scope: 'global', // The name of the scope for this provider\n  path: '/Users/fabio/.config/myapp/global.json', // Path where to persist data\n  watching: true, // Whether to watch the file for changes too or not\n  defaults: {}, // The default settings object for this provider\n  defaultsRaw: '{\\n\\t// Write global-level settings here\\n}' // The default settings object for this provider as a string\n});\n\nconst configuration = new Configuration ({\n  providers: [Window, Local, Global], // List of custom providers used, ordered by priority\n  defaults: { // The default settings object for the implicit \"defaults\" scope\n    some: {\n      default: {\n        settings: true\n      }\n    }\n  },\n  filter: settings =\u003e { // Custom optional function for manipulating the raw settings object\n    // Optionally filter down the passed \"settings\" object...\n    return settings;\n  }\n});\n\n// Using the #get method\n\nconfiguration.get (); // Get the entire merged object\nconfiguration.get ( '*' ); // Get the entire object for each scope\nconfiguration.get ( '*', 'some.path' ); // Get the value at \"some.path\" for all scopes\nconfiguration.get ( 'local', 'some.path' ); // Get the value at \"some.path\" from the \"local\" scope\nconfiguration.get ( 'some.path' ); // Get the value at \"some.path\" from the first scope that has a value for it\n\n// Using the #has method\n\nconfiguration.has ( '*', 'some.path' ); // Check if a value exists at \"some.path\" in all scopes\nconfiguration.has ( 'local', 'some.path' ); // Check if a value exists at \"some.path\" in the \"local\" scope\nconfiguration.has ( 'some.path' ); // Check if a value exists at \"some.path\" in at least one scope\n\n// Using the #remove method\n\nconfiguration.remove ( '*', 'some.path' ); // Remove the \"some.path\" key from all scopes\nconfiguration.remove ( 'local', 'some.path' ); // Remove the \"some.path\" key from the \"local\" scope\nconfiguration.remove ( 'some.path' ); // Remove the \"some.path\" key from any scope that has a value for it\n\n// Using the #reset method\n\nconfiguration.reset (); // Reset the value of every scope to its default one\nconfiguration.reset ( 'local' ); // Reset the value of the \"local\" scope\n\n// Using the #set method\n\nconfiguration.set ( '*', 'some.path', 123 ); // Set \"123\" as the value at \"some.path\" for every scope\nconfiguration.set ( 'local', 'some.path', 123 ); // Set \"123\" as the value at \"some.path\" for the \"local\" scope\nconfiguration.set ( 'some.path', 123 ); // Set \"123\" as the value at \"some.path\" in the first scope that has a value for that key\n\n// Using the #update method\n\nconfiguration.update ( '*', { something: {} } ); // Replacing the entire settings object for every scope\nconfiguration.update ( 'local', { something: {} } ); // Replacing the entire settings object for the \"local\" scope\n\n// Listening for changes\n\nconfiguration.onChange ( () =\u003e {\n  // Something changed anywhere in the object, but we don't know exactly where, but this makes this callback the cheapest\n});\n\nconfiguration.onChange ( 'local', 'some.path', ( value, valuePrev ) =\u003e {\n  // The value of \"some.path\" in the \"local\" scope changed\n});\n\nconfiguration.onChange ( 'some.path', ( value, valuePrev ) =\u003e {\n  // The value of \"some.path\" in the first scope that provides a value for it changed\n});\n\n// Let's dispose of the configuration object, stopping filesystem watching for example\n\nconfiguration.dispose ();\n```\n\n## License\n\nMIT © Fabio Spampinato\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fconfiguration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiospampinato%2Fconfiguration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fconfiguration/lists"}