{"id":13483742,"url":"https://github.com/beginner-corp/begin-data","last_synced_at":"2025-03-27T15:30:36.299Z","repository":{"id":43271151,"uuid":"148850287","full_name":"beginner-corp/begin-data","owner":"beginner-corp","description":"A durable and fast key/value store for Begin built on top of DynamoDB","archived":false,"fork":false,"pushed_at":"2024-05-21T14:40:25.000Z","size":365,"stargazers_count":78,"open_issues_count":9,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-19T11:42:34.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/beginner-corp.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","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":"2018-09-14T23:10:14.000Z","updated_at":"2025-03-03T20:46:03.000Z","dependencies_parsed_at":"2024-05-18T22:21:44.789Z","dependency_job_id":"af2ece86-655f-4eef-83e1-dd76ba3299f2","html_url":"https://github.com/beginner-corp/begin-data","commit_stats":{"total_commits":170,"total_committers":14,"mean_commits":"12.142857142857142","dds":0.6529411764705882,"last_synced_commit":"97cee1409561973b85d82ca64d41cb852895777a"},"previous_names":["smallwins/begin-data"],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Fbegin-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Fbegin-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Fbegin-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beginner-corp%2Fbegin-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beginner-corp","download_url":"https://codeload.github.com/beginner-corp/begin-data/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245871682,"owners_count":20686246,"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-31T17:01:14.803Z","updated_at":"2025-03-27T15:30:32.696Z","avatar_url":"https://github.com/beginner-corp.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Begin Data\n## [`@begin/data`](https://www.npmjs.com/package/@begin/data)\n\n[![GitHub CI status](https://github.com/smallwins/begin-data/workflows/Node%20CI/badge.svg)](https://github.com/smallwins/begin-data/actions?query=workflow%3A%22Node+CI%22)\n\nBegin Data is an easy to use, fast, and durable key/value and document store built on top of DynamoDB. Originally built for [Begin serverless apps](https://begin.com), Begin Data’s core API has three simple methods: `get`, `set`, and `destroy`.\n\n## Concepts\n\nBegin Data organizes itself into `table`s. A `table` contain documents which are just collections of plain Objects. Documents stored in Begin Data always have the properties `table` and `key`.\n\nOptionally a document can also have a `ttl` property with a UNIX epoch value representing the expiry time for the document.\n\n## Usage\n\nBegin Data operates on one DynamoDB table named `data` with a partition key `scopeID` and a sort key of `dataID` (and, optionally, a `ttl` for expiring documents).\n\nExample `app.arc`:\n\n```\n@app\nmyapp\n\n@tables\ndata\n  scopeID *String\n  dataID **String\n  ttl TTL\n```\n\nOr equivalent CloudFormation YAML:\n\n```yaml\nAWSTemplateFormatVersion: \"2010-09-09\"\nResources:\n    BeginData:\n        Type: \"AWS::DynamoDB::Table\"\n        Properties:\n            TableName: \"data\"\n            BillingMode: \"PAY_PER_REQUEST\"\n            KeySchema:\n              -\n                AttributeName: \"scopeID\"\n                KeyType: \"HASH\"\n              -\n                AttributeName: \"dataID\"\n                KeyType: \"RANGE\"\n            SSESpecification:\n                Enabled: \"false\"\n            TimeToLiveSpecification:\n                AttributeName: \"ttl\"\n                Enabled: \"TRUE\"\n```\n\n\u003e Note: projects not based on [Architect](https://arc.codes) will need a `BEGIN_DATA_TABLE_NAME` environment variable. You can also use this env var to override and name the table anything you want. This also allows for multiple apps to share a single table.\n\n### API\n\n```javascript\nlet data = require('@begin/data')\n```\n\nThe core API is three methods:\n\n- `data.get(params[, callback])` → `[Promise]` for retreiving data\n- `data.set(params[, callback])` → `[Promise]` for writing data\n- `data.destroy(params[, callback])` → `[Promise]` for removing data\n\nAdditional helper methods are also made available:\n\n- `data.incr(params[, callback])` → `[Promise]` increment an attribute on a document\n- `data.decr(params[, callback])` → `[Promise]` decrement an attribute on a document\n- `data.count(params[, callback])` → `[Promise]` get the number of documents for a given table\n\nAll methods accept a params object and, optionally, a Node-style errback. If no errback is supplied, a Promise is returned. All methods support `async`/`await`.\n\n#### Writes\n\nSave a document in a `table` by `key`. Remember: `table` is required; `key` is optional.\n\n```javascript\nlet taco = await data.set({\n  table: 'tacos',\n  key: 'al-pastor'\n})\n```\n\nAll documents have a `key`. If no `key` is given, `set` will generate a unique `key`.\n\n```javascript\nlet token = await data.set({\n  table: 'tokens',\n})\n// {table:'tokens', key:'LCJkYX9jYWwidW50RhSU'}\n```\n\nBatch save multiple documents at once by passing an Array of Objects.\n\n```javascript\nlet collection = await data.set([\n  {table: 'ppl', name:'brian', email:'b@brian.io'},\n  {table: 'ppl', name:'sutr0', email:'sutr0@brian.io'},\n  {table: 'tacos', key:'pollo'},\n  {table: 'tacos', key:'carnitas'},\n])\n```\n\n#### Reads\n\nRead a document by `key`:\n\n```javascript\nlet yum = await data.get({\n  table: 'tacos',\n  key: 'baja'\n})\n```\n\nBatch read by passing an Array of Objects. With these building blocks you can construct secondary indexes and joins, like one-to-many and many-to-many.\n\n```javascript\nawait data.get([\n  {table:'tacos', key:'carnitas'},\n  {table:'tacos', key:'al-pastor'},\n])\n```\n\n#### Destroy\n\nDelete a document by `key`.\n\n```javascript\nawait data.destroy({\n  table: 'tacos',\n  key: 'pollo'\n})\n```\n\nBatch delete documents by passing an Array of Objects.\n\n```javascript\nawait data.destroy([\n  {table:'tacos', key:'carnitas'},\n  {table:'tacos', key:'al-pastor'},\n])\n```\n\n## Pagination\n\nLarge sets of data can not be retrieved in one call because the underlying `get` api paginates results.\nIn this case use the `for await` syntax with a limit set to get paginated data.\n\n```javascript\nlet pages = data.page({ table:'ppl', limit:25 })\nlet count = 0  \nfor await (let page of pages) {\n  console.log(page)\n  count++\n}\n```\n\n## Additional Superpowers\n\n- Documents can be expired by setting `ttl` to an UNIX epoch in the future.\n- Atomic counters: `data.incr` and `data.decr`\n\nSee the tests for more examples!\n\n## Patterns\n\nComing soon! Detailed guides for various data persistence tasks:\n\n- Denormalizing\n- Pagination\n- Counters\n- Secondary indexes\n- One to many\n- Many to many\n\n## More\n\n- [Try out Begin Data on Begin!](https://begin.com)\n- [Learn more about Begin Data](https://docs.begin.com/en/data/begin-data/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeginner-corp%2Fbegin-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeginner-corp%2Fbegin-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeginner-corp%2Fbegin-data/lists"}