README

PackageName Type for Typescript

Introduction

This TypeScript micro-library provides a PackageName type, along with helpers for validating the data.

Introduction
Quick Start
V1 API
NPM Scripts

Quick Start

# run this from your Terminal
npm install @ganbarodigital/ts-lib-packagename/v1

// add this import to your Typescript code
import { PackageName, packageNameFrom } from "@ganbarodigital/ts-lib-packagename/lib/v1"

VS Code users: once you've added a single import anywhere in your project, you'll then be able to auto-import anything else that this library exports.

V1 API

PackageName

/**
 * represents the name of a TypeScript package
 *
 * the package can be:
 * - any valid NPM package name
 * - and can include sub-package names too
 *
 * Sub-package names can include uppercase characters.
 *
 * examples of valid PackageNames include:
 *
 * - ts-lib-packagename
 * - @ganbarodigital/ts-lib-packagename
 * - @ganbarodigital/ts-lib-packagename/v1
 * - @ganbarodigital/ts-lib-packagename/V1/types
 *
 * Relative module names are not supported.
 *
 * At runtime, PackageName resolves to being just a `string`.
 */
export type PackageName = string & { "@ganbarodigital/PackageName": "@ganbarodigital/PackageName" };

PackageName is a type. (Strictly speaking, it's a branded type.) Use it to represent a valid TypeScript package name in type-safe code.

Use packageNameFrom() to create PackageName values.

packageNameFrom()

import { OnError, THROW_THE_ERROR } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

/**
 * smart constructor. Checks that the input string is a valid package name,
 * and converts it into a PackageName type.
 */
export function packageNameFrom(name: string, onError: OnError = THROW_THE_ERROR): PackageName;

packageNameFrom() is a smart constructor. Use it to turn strings into PackageName types.

isPackageNameData()

/**
 * data guard. confirms if a proposed name for a PackageName fits
 * our legal scheme or not.
 */
export function isPackageNameData(name: string): boolean;

isPackageNameData() is a data guard. Use it to determine if the input string contains a valid PackageName or not.

We do not check that the named package actually exists. We only check that the name meets our naming structure.

mustBePackageNameData()

import { OnError, THROW_THE_ERROR } from "@ganbarodigital/ts-lib-error-reporting/lib/v1";

/**
 * data guarantee. calls the supplied OnError handler if the input string
 * does not meet the specification for a valid PackageName.
 */
export function mustBePackageNameData(name: string, onError: OnError = THROW_THE_ERROR): void;

mustBePackageNameData() is a data guarantee. Use it to ensure that you're handling a valid PackageName string.

NPM Scripts

npm run clean

Use npm run clean to delete all of the compiled code.

npm run build

Use npm run build to compile the Typescript into plain Javascript. The compiled code is placed into the lib/ folder.

npm run build does not compile the unit test code.

npm run test

Use npm run test to compile and run the unit tests. The compiled code is placed into the lib/ folder.

npm run cover

Use npm run cover to compile the unit tests, run them, and see code coverage metrics.

Metrics are written to the terminal, and are also published as HTML into the coverage/ folder.

Usage no npm install needed!