Access
Get deeply nested properties from unknown shapes with at-runtime type safety.
Access allows you to get values in unknown
or any
types and be assured you will get the correct type out. If the value is missing, undefined, or the incorrect type, the given fallback is returned instead. This is achieved with at-runtime type checking. A global callback can also be registered to be called anytime a fallback is returned.
Installation
yarn
yarn add access
npm
npm install access
Example
; ; getStringapiResponse, x.data.user.address.state, 'state not found'; // "MA"getStringapiResponse, x.missing.key, 'fallback'; // fallbackgetNumberapiResponse, x.data.user.address.state, 999; // 999
API
getString
getStringobj: ObjectType, accessor:ReturnType, fallback: string, callback?:void): string
getNumber
getNumberobj: ObjectType, accessor:ReturnType, fallback: number, callback?:void: number
getBoolean
getBooleanobj: ObjectType, accessor:ReturnType, fallback: boolean, callback?:void: boolean
getStringArray
getStringArrayobj: ObjectType, accessor:ReturnType, fallback: string, callback?:void: string
getNumberArray
getNumberArrayobj: ObjectType, accessor:ReturnType, fallback: number, callback?:void: number
getBooleanArray
getBooleanArrayobj: ObjectType, accessor:ReturnType, fallback: boolean, callback?:void: boolean
getStringMap
getStringMapobj: ObjectType, accessor:ReturnType, fallback: , callback?:void:
getNumberMap
getNumberMapobj: ObjectType, accessor:ReturnType, fallback: , callback?:void:
getBooleanMap
getBooleanMapobj: ObjectType, accessor:ReturnType, fallback: , callback?:void:
Configuration
A callback can be registered with the default access
export. This callback will be called anytime a fallback is returned.
A typical usecase for this is to send a message to some error tracking software signaling that a CMS or some other remote server is no longer returning data in a shape that we expected. See the example below:
Configuration Example
getter.ts
; ; ;
example.ts
; }; getStringapiResponse, x.missing.key, 'fallback text'; // "fallback text"// error ('ui.fallback.returned', PropertyMissingException...) was sent to ErrorTracker
Related Projects
ts-get
and idx
share the same goals and API as this one. The biggest difference is that this library works against unknown
types, whereas the others require the accessed object to be explicitly typed with optional types. Neither library does runtime checking to prevent against type mismatches either.
FAQ
Why not use a generic type signature?
The library was originally implemented as one generic get
function. It looked something like:
;;;;;;
This generic implementation — while having a much smaller surface area — had large performance implications, especially when dealing with arrays and maps. Due to the nature of the runtime typechecking, the fallback and return value had to be checked against all possible return types to be able to infer which type to return. Therefor multiple (more specific) methods were chosen over this simpler syntax.