{"id":23440777,"url":"https://github.com/dabapps/simple-records","last_synced_at":"2025-04-09T20:37:29.114Z","repository":{"id":57105342,"uuid":"107653533","full_name":"dabapps/simple-records","owner":"dabapps","description":"Simple Readonly TypeScript Records","archived":false,"fork":false,"pushed_at":"2019-04-01T14:28:45.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-06T11:47:12.779Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dabapps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-20T08:39:29.000Z","updated_at":"2019-09-17T08:46:07.000Z","dependencies_parsed_at":"2022-08-20T23:50:09.156Z","dependency_job_id":null,"html_url":"https://github.com/dabapps/simple-records","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabapps%2Fsimple-records","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabapps%2Fsimple-records/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabapps%2Fsimple-records/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dabapps%2Fsimple-records/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dabapps","download_url":"https://codeload.github.com/dabapps/simple-records/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248108842,"owners_count":21049209,"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-12-23T16:18:36.503Z","updated_at":"2025-04-09T20:37:29.094Z","avatar_url":"https://github.com/dabapps.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simple Records\n\n**Simple Readonly TypeScript Records**\n\n[![Build Status](https://travis-ci.com/dabapps/simple-records.svg?token=Vjwq9pDHXxGNhnyuktQ5\u0026branch=master)](https://travis-ci.com/dabapps/simple-records)\n\nThis module provides a number of helper functions for working with TypeScript ReadOnly objects.\n\n## Disclaimer\n\nThis module is in its early stages and until it reaches its first major version it may be unstable, with potentially breaking changes with new minor version releases.\n\nPatch version changes will include both minor changes and patches.\n\n## Installation\n\nInstall via NPM:\n\n```shell\nnpm install @dabapps/simple-records --save\n```\n\nIf you are using a version of npm that doesn't support package lock files, we'd recommend installing with the `--save-exact` flag to pin to a specific version in your package.json.\n\n## Available interfaces\n\n### Dict\n\nDict is a simple type alias for a Readonly Object with arbitrary string keys.\n\n```typescript\nconst x: Dict\u003cstring\u003e = {\n  arbitrary: 'data',\n};\n\n```\n\n### JSON and ReadonlyJSON\n\nWhen dealing with unknown recursive data shapes from a server, you can specify them as JSON or ReadonlyJSON;\n\n```typescript\nconst x: JSON = {\n  hi: {\n    there: [\n      1, 2, 3, 'a'\n    ]\n  }\n}\n```\n\n### SimpleRecord\n\nSimpleRecord creates a function that produces a given Readonly interface, with default values for keys that aren't provided.\n\n```typescript\ntype IMyRecord = Readonly\u003c{\n  a: string;\n  b: number;\n}\u003e;\n\nconst MyRecord = SimpleRecord\u003cIMyRecord\u003e({\n  a: 'default string for a',\n  b: 0\n});\n\nconst myInstance = MyRecord({\n  b: 5\n});\n\n// myInstance == {\n//   a: 'default string for a',\n//   b: 5\n// }\n```\n\n### RecordWithConstructor\n\nRecordWithConstructor takes an input interface of raw data, an output interface of completed data, a set of defaults for the input, and a callback function that must translate between the two types. This is used for when you have complex types (such as nested records, or Moment objects).\n\n```typescript\ntype IMyRecordInput = Readonly\u003c{\n  a: string;\n  b: string | Date;\n}\u003e;\n\ntype IMyRecord = Readonly\u003c{\n  a: string;\n  b: moment.Moment;\n}\u003e;\n\nconst MyRecord = RecordWithConstructor\u003cIMyRecordInput, IMyRecord\u003e({\n  a: '',\n  b: new Date(),\n}, (input) =\u003e {\n  return {\n    ...input,\n    b: moment.utc(input.b)\n  };\n});\n\nconst myInstance = MyRecord({b: '1970-01-01'});\n// myInstance.b is now a Moment object\n```\n\n### Proplist\n\nA proplist is an array of 2-tuples of shape `[string, T]`, often used to represent simple ordered dictionary types and cases where mutiple keys may exist for the same item.  They can be converted to Dicts, but duplicate keys beyond the first will be discarded and ordering will be lost.\n\n```typescript\nconst myProplist: Proplist\u003cnumber\u003e = [['a', 1], ['b', 2], ['b', 3]];\n\nconst myDict = proplistToDict(myProplist);\n// myDict == {\n//   a: 1,\n//   b: 2\n// }\n\nconst myOtherProplist = dictToProplist({a: 1, b: 2});\n// myOtherProplist == [\n//   ['a', 1],\n//   ['b', 2],\n// ];\n// // Order is not guaranteed as Dict is unordered.\n```\n\nThere is also a MutableProplist type, for times when you need mutability.\n\n\n### OrderedDict\n\nAn OrderedDict is an object that combines the guaranteed order characteristics of an Array with the indexability of a Dict.  They can be created from Dicts (although, bare in mind Dicts are not ordered so you will need to provide a sort, otherwise it will sort alphabetically by key), and from Proplists (which will cause duplicate values to be dropped).  They can also be created from scratch.  It is not recommended as it is error-prone, but you can also initialize them with a list of keys, and a dictionary of items.\n\n```typescript\nconst orderedDict1 = new OrderedDict\u003cnumber\u003e();\nconst orderedDict2 = OrderedDict.fromDict({'a': 1, 'b': 2, 'c': 3});\nconst orderedDict3 = OrderedDict.fromProplist([['a', 1], ['b', 2], ['c', 3]]);\n\n// Don't do this unless you're really sure\nconst handInitialized = new OrderedDict\u003cnumber\u003e(['a', 'b', 'c'], {'a': 1, 'b': 2, 'c': 3});\n\nconst orderedDictUpdated = orderedDict2.set('b', 5);\nconst valueOfB = orderedDictUpdated.get('b');\n\nconst orderedDictMerged = orderedDict2.merge(orderedDict3, ([leftKey, leftValue], [rightKey, rightValue]) =\u003e leftValue - rightValue);\n```\n\nAdditional Array-like methods are provided to match the behaviour of native Arrays.\n\n## Code of conduct\n\nFor guidelines regarding the code of conduct when contributing to this repository please review [https://www.dabapps.com/open-source/code-of-conduct/](https://www.dabapps.com/open-source/code-of-conduct/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdabapps%2Fsimple-records","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdabapps%2Fsimple-records","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdabapps%2Fsimple-records/lists"}