@type-magic/color-identity v1.1.0
type-magic 🧙
Typescript library for working with the Magic color identity system
Table of Contents
Features
- Type safety and IDE autocomplete for Magic color identity strings
- Use the
ColorIdentityStringtype to enforce the color identity syntax for strings - The static API of
ColorIdentityoffers methods for working with color identities such asadd,subtract,contains,gte,subColorIdentitiesand many more - Instances of
ColorIdentityprovide a fluent interface for the same methods
Usage Examples
Installation in a npm project
Install the library in any npm project and import from @type-magic/color-identity:
ColorIdentityString type
// Define a ColorIdentityString to get strong typing for wubrg strings
const myId: ColorIdentityString = 'wubrg'
const myOtherId: ColorIdentityString = 'wbg'
const myThirdId: ColorIdentityString = ''
// const doesntCompile: ColorIdentityString = 'xyz' // Error!Static API of ColorIdentity
// Use the static ColorIdentity API to work with color identity strings
ColorIdentity.add('wub', 'brg') // returns 'wubrg'
ColorIdentity.contains('wubr', 'br') // returns true
ColorIdentity.lt('u', 'ub') // returns true
ColorIdentity.components('wub') // returns ['', 'w', 'u', 'b']
ColorIdentity.subColorIdentities('wg') // returns ['', 'g', 'w', 'wg']Create ColorIdentity objects
const myObj = new ColorIdentity('wubrg') // only accepts ColorIdentityString input
const myOtherObj = ColorIdentity.parse('wubrg') // accepts any string input and throws if invalid
const myThirdObj = ColorIdentity.parse('invalid') // Error!Fluent interface API of ColorIdentity objects
myObj
.subtract(ColorIdentity.FULL)
.add('wbg')
.subtract('b')
.subColorIdentities() // ['', 'g', 'w', 'wg']The cid tagged template function
// Regular syntax
const myCid = cid`wubrg`
// With template interpolation
const interpolationValue = "wu"
const myOtherCid = cid`${interpolationValue}brg`
// Syntax ok, but will throw an error when executed
const myThirdCid = cid`will compile but throw error`What is a Tagged Template?
A tagged template in Typescript is a template string tagged with a function. The template string behaves just like a regular Typescript template string. However, instead of the regular string interpolation, the tag function must implement how the template is supposed to be parsed. In short, a tagged template is a special way to parse template strings.
In the case of the cid function, it actually does nothing more than a regular template string would.
It receives the TemplateStringsArray and the args, then joins them and calls ColorIdentity.parse with the input.
The cid function is basically just a shortcut or syntactic sugar for calling ColorIdentity.parse.
However, this can be used in very interesting ways, like for example an IDE plugin for syntax highlighting for cid tagged templates.
Development
The scripts section of the package.json file contains everything that is needed
for working on this library.
| Script | Description |
|---|---|
clean | Deletes the dist/ and coverage/ directories that are generated when building or testing the project. |
build | Builds the project using tsc . This build is used for active development and debugging purposes. |
build:prod | Builds the project, but swaps out the build configuration file ( tsconfig.prod.json ). This build is used for public releases of this library. |
test | Runs all tests for the project with code coverage using jest. |
test:watch | Starts the jest unit test runner in watch mode. |
lint | Scans all typescript files for linting errors as specified in .eslintrc.js . |
lint:fix | Runs the lint check and fixes each error if possible. |
prepublish | An npm hook that is invoked whenever a version of this library is about to be npm published. |