property-tunnel: aliases to reduce boilerplate in Typescript and Javascript
This library bores tunnels from one object property to another object property in order to create aliases. Includes a decorator for use on class properties (both instance and static).
Installation
Yarn: yarn add property-tunnel
npm: npm install --save property-tunnel
Typescript
To use @alias
you need to set experimentalDecorators: true
in your
tsconfig.json
.
Targeting ES5 and below
If you want to use @alias
to make a class iterable you'll need to set
downlevelIteration: true
in your tsconfig.json
.
Javascript
To use @alias
you need to use the transform-decorators
Babel plugin.
API
The public API is what is available directly via the 'property-tunnel' module. Everything else is subject to change. These are:
@alias(["property", "to", "alias"], { <options> })
A decorator for use on class properties that creates an alias to another property or subproperty of the same class. Works on both instance and static properties.
It takes one or two arguments: an array of property keys that designates the property to alias and an options object.
Options are described by the AliasOptions interface.
Example 1: Null-safe alias for a deeply nested property
;
Example 2: Using an alias to make a class iterable through a property
; ;// Add a second sheet (see constructor)workbook.createSheet"My Sheet";for of workbook // prints: "Untitled 0", "My Sheet"
interface AliasOptions
Contains four options, none of which are required:
;
tunnel(to, key, { <options> })
Used to create a tunnel on an arbitrary object. Used by alias
to implement
class property aliases.
Options are described by the TunnelOptions interface.
Usage
;;tunnelproxy, "alias", ;console.logproxy.alias; // prints "foobar"proxy.alias = "bazquirk";console.logdestination.prop; // prints "bazquirk"
interface TunnelOptions
Contains all of the options from AliasOptions
plus destination
and
destinationPath
.
;
type TunnelAccess = "readonly" | "readwrite"
Literally one of the strings "readonly"
or "readwrite"
.
interface TunnelConverter
Used to specify two functions that convert between the alias/tunnel and destination values.
You might use this to convert between types or to reformat values.
Usage
; ;progress.value = 05;console.logprogress.percent; // prints: 50progress.percent = 100;console.logprogress.value; // prints: 1
PropertyTunnel class
This is a lower level class that can be used if you ever need to connect multiple tunnels to the same destination.
It's unlikely you'll ever need to use this. The tunnel()
function uses it
internally and returns the instance it creates.
If you find you need to use it have a look at the src/PropertyTunnel.ts
file,
it's heavily commented.
Notes
I've liberated this library from one of my own proprietary projects. Some of the code that isn't part of the public API has much greater reuse value in the original project.
For the time being I've included some of that code in this library but it will be moved to another open source library I'll be releasing in good time.
It's for this reason that it's particularly important that you don't use anything that isn't explicitly included in the public API as summarised above.