@dabapps/simple-records
v0.1.8
Published
Simple Readonly TypeScript Records
Downloads
89
Readme
Simple Records
Simple Readonly TypeScript Records
This module provides a number of helper functions for working with TypeScript ReadOnly objects.
Disclaimer
This 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.
Patch version changes will include both minor changes and patches.
Installation
Install via NPM:
npm install @dabapps/simple-records --save
If 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.
Available interfaces
Dict
Dict is a simple type alias for a Readonly Object with arbitrary string keys.
const x: Dict<string> = {
arbitrary: 'data',
};
JSON and ReadonlyJSON
When dealing with unknown recursive data shapes from a server, you can specify them as JSON or ReadonlyJSON;
const x: JSON = {
hi: {
there: [
1, 2, 3, 'a'
]
}
}
SimpleRecord
SimpleRecord creates a function that produces a given Readonly interface, with default values for keys that aren't provided.
type IMyRecord = Readonly<{
a: string;
b: number;
}>;
const MyRecord = SimpleRecord<IMyRecord>({
a: 'default string for a',
b: 0
});
const myInstance = MyRecord({
b: 5
});
// myInstance == {
// a: 'default string for a',
// b: 5
// }
RecordWithConstructor
RecordWithConstructor 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).
type IMyRecordInput = Readonly<{
a: string;
b: string | Date;
}>;
type IMyRecord = Readonly<{
a: string;
b: moment.Moment;
}>;
const MyRecord = RecordWithConstructor<IMyRecordInput, IMyRecord>({
a: '',
b: new Date(),
}, (input) => {
return {
...input,
b: moment.utc(input.b)
};
});
const myInstance = MyRecord({b: '1970-01-01'});
// myInstance.b is now a Moment object
Proplist
A 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.
const myProplist: Proplist<number> = [['a', 1], ['b', 2], ['b', 3]];
const myDict = proplistToDict(myProplist);
// myDict == {
// a: 1,
// b: 2
// }
const myOtherProplist = dictToProplist({a: 1, b: 2});
// myOtherProplist == [
// ['a', 1],
// ['b', 2],
// ];
// // Order is not guaranteed as Dict is unordered.
There is also a MutableProplist type, for times when you need mutability.
OrderedDict
An 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.
const orderedDict1 = new OrderedDict<number>();
const orderedDict2 = OrderedDict.fromDict({'a': 1, 'b': 2, 'c': 3});
const orderedDict3 = OrderedDict.fromProplist([['a', 1], ['b', 2], ['c', 3]]);
// Don't do this unless you're really sure
const handInitialized = new OrderedDict<number>(['a', 'b', 'c'], {'a': 1, 'b': 2, 'c': 3});
const orderedDictUpdated = orderedDict2.set('b', 5);
const valueOfB = orderedDictUpdated.get('b');
const orderedDictMerged = orderedDict2.merge(orderedDict3, ([leftKey, leftValue], [rightKey, rightValue]) => leftValue - rightValue);
Additional Array-like methods are provided to match the behaviour of native Arrays.
Code of conduct
For guidelines regarding the code of conduct when contributing to this repository please review https://www.dabapps.com/open-source/code-of-conduct/