{"id":15917601,"url":"https://github.com/dsfields/kibbutz","last_synced_at":"2025-04-03T11:42:01.297Z","repository":{"id":82746532,"uuid":"71161425","full_name":"dsfields/kibbutz","owner":"dsfields","description":"Configuration aggregator for Node.js","archived":false,"fork":false,"pushed_at":"2018-03-22T17:00:31.000Z","size":40,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-09T03:16:04.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/dsfields.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2016-10-17T17:02:26.000Z","updated_at":"2018-03-22T17:00:33.000Z","dependencies_parsed_at":"2023-06-18T02:45:57.480Z","dependency_job_id":null,"html_url":"https://github.com/dsfields/kibbutz","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"3a3a9a370956539d3ada3fc6dd98aeafd39638d8"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fkibbutz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fkibbutz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fkibbutz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dsfields%2Fkibbutz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dsfields","download_url":"https://codeload.github.com/dsfields/kibbutz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246998102,"owners_count":20866690,"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-10-06T18:11:49.154Z","updated_at":"2025-04-03T11:42:01.277Z","avatar_url":"https://github.com/dsfields.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kibbutz\n\nCommunal gathering of configuration artifacts.\n\nKibbutz loads fragments of configuration from multiple sources, and merges them into a single JSON object.\n\n## Usage\n\nAdd `kibbutz` as a dependency in `package.json`:\n\n```sh\n$ npm install kibbutz -S\n```\n\nCreate an instance of `Kibbutz`, and give it configuration and/or a list of providers from which to load configuration data:\n\n```js\nconst Kibbutz = require('kibbutz');\n\nconst config = new Kibbutz({\n  value: {\n    foo: 'bar'\n  }\n});\n\nconst myProvider = {\n  load: function(callback) {\n    // load configuration data from somewhere\n    callback(undefined, configFragment);\n  }\n};\n\nconfig.load([ myProvider ], function(err, config) {\n  // do something beautiful with your configuration\n});\n```\n\n## API\n\n### Constructors\n\n#### `new Kibbutz([options])`\n\nCreates an instance of `Kibbutz`.\n\n##### Parameters\n\n  * `options`: _(optional)_ an object with the following keys:\n\n    + `value`: _(optional)_ the base configuration object.  Kibbutz will make a deep copy of this object, which will become the value of `Kibbutz.prototype.value`.  All other configuration fragments loaded via provider with `Kibbutz.prototype.load()` are merged into this object.\n\n##### Example\n\n```js\nconst Kibbutz = require('kibbutz');\n\nconst config = new Kibbutz({\n  value: {\n    foo: 'bar',\n    baz: 'qux'\n  }\n});\n\nconsole.log(config.value.foo); // bar\nconsole.log(config.value.baz); // qux\n```\n\n### Properties\n\n#### `Kibbutz.shared`\n\nGets or sets a globally shared instance of `Kibbutz`.  This value must be `null` or an instance of `Kibbutz`.  The default is `null`.\n\n#### `Kibbutz.prototype.value`\n\nGets the full configuration object.  This is the merged configuration JSON object from all providers supplied to `Kibbutz.prototype.load()`, and the seed value supplied via options to the constructor.  The object return is immutable, and attempts to modify it will result in an error.\n\n##### Example\n\n```js\nconst Kibbutz = require('kibbutz');\n\nconst config = new Kibbutz({\n  value: { foo: 'bar' }\n});\n\nconfig.load([{\n  load: function(callback) {\n    callback({ baz: 'qux' });\n  }\n}]);\n\nconsole.log(config.value.foo); // bar\nconsole.log(config.value.baz); // qux\n```\n\n### Methods\n\n#### `Kibbutz.prototype.append(obj0[, objN] | objs)`\n\nAppends an object, or series of objects to the existing `Kibbutz.prototype.value`.\n\n##### Parameters\n\n  * `obj0[, objN]`: a series of objects to merge into the configuration.  At least on is required.\n\n...or...\n\n  * `objs`: an array of objects to merge into the configuration.\n\n##### Returns\n\nThe same instance of `Kibbutz`.  This allows multiple method calls to be chained together.\n\n#### `Kibbutz.prototype.load(providers, callback)`\n\nLoads configuration fragments from the given array of `providers`, and merges them together.\n\n##### Parameters\n\n  * `providers`: _(required)_ an array of providers used to load configuration fragments.\n\n  * `callback`: _(required)_ a function invoked when al providers have completed loading.  The expected function signature takes two parameters:\n\n    + `err`: an error returned from one of the providers.\n\n    + `config`: the fully merged configuration value.  This is the same as `Kibbutz.prototype.value`.\n\n##### Returns\n\nThe same instance of `Kibbutz`.  This allows multiple method calls to be chained together.\n\n##### Providers\n\nProviders are run serially by how they are ordered in the `providers` array.  One provider does not execute until the previous has completed loading.  In the event one provider fails, no succeeding providers are run.  A provider must be an object with the following signature:\n\n  * `load(callback)`: a method that loads a configuration fragment.  The method takes a single parameter:\n\n    + `err`: an error object passed to the callback.  If no error occurred, the provider must pass in `undefined` or `null`.\n\n    + `fragment`: the configuration fragment loaded by the provider.  This value is ignored if `err` has a value.\n\n##### Merging\n\nConfiguration fragments are merged into the base config element managed by `Kibbutz`.  Keys use a first-in-wins strategy, meaning, once a key is set it cannot be set by a different provider.  The exception being objects and arrays.  Objects are deep-merged, and arrays are concatenated.\n\n#### `Kibbutz.prototype.loadAsync(providers)`\n\nWorks just like [`Kibbutz.prototype.load()`](#kibbutzprototypeloadproviders-callback), but returns a `Promise`.\n\n##### Parameters\n\n  * `providers`: _(required)_ an array of [providers](#providers) used to load configuration fragments.\n\n##### Returns\n\nThe a `Promise` that resolves with the fully merged configuation value.  This is the same as `Kibbutz.prototype.value`.\n\n#### `Kibbutz.prototype.on(eventName, listener)`\n\n`Kibbutz` emits events which can be subscribed to via the `on()` method.  This method functions just like the native Node.js [`EventEmitter.prototype.on()`](https://nodejs.org/api/events.html#events_emitter_on_eventname_listener) method.\n\n##### Parameters\n\n  * `eventName`: _(required)_ the name of the even to which your `listener` is subscribed.\n\n  * `listener`: _(required)_ the function used to handle an event.  Each function signature should follow the expected contract for the associated event.  See below for more details.\n\n##### Returns\n\nThe same instance of `Kibbutz`.  This allows multiple method calls to be chained together.\n\n##### Events\n\n  * `config`: raised when a provider's `load()` responds with data.  Listeners should have the following parameters:\n\n    + `providerName`: the name of the provider.\n\n    + `fragment`: the the configuration fragment that has been loaded from the provider.\n\n  * `done`: raised when all providers given to `Kibbutz.prototype.load()` have completed.    Listeners should have the following parameters:\n\n    + `config`: the full configuration JSON object.\n\n##### Example\n\n```js\nconst Kibbutz = require('kibbutz');\n\nconst config = new Kibbutz();\n\nconfig.on('error', function(err) {\n  console.log(err);\n})\n.on('config', function(providerName, fragment) {\n  console.log(`${providerName}: ${fragment}`);\n})\n.on('done', function(config) {\n  myThing.configure(config);\n});\n```\n\n## Provider Implementations\n\nThe following are known Kibbutz provider implementations.  _If you've created one not listed here, please add it to the README.md file via pull request in the [GitHub project](https://github.com/dsfields/kibbutz)._\n\n  * [`kibbutz-rc`](https://www.npmjs.com/package/kibbutz-rc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fkibbutz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsfields%2Fkibbutz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsfields%2Fkibbutz/lists"}