@marktuk/banner

A simple tool that will apply a custom banner comment to multiple files in a project.

There are a few existing tools that can be used to write a banner comment to files in a project. However, many of them are not actively maintained, and no single tool had the all of features I wanted. This tool provides the following features:

• Apply banner comments to files matching a specified glob pattern
• Configure multiple banner comment templates for different glob patterns
• Use placeholders in banner templates to merge in values from a package.json

Table of Contents

• Install
• Usage
  • Configuration
  • CLI
  • API
• Contributing
• Licence

Install

$ npm install --save-dev @marktuk/banner

Usage

Configuration

The templates can be configured by adding a banner object to your package.json.

The configuration should be an object where each value is a template as an array of strings and it's key is a glob pattern to use to apply the template to matching files.

The templates support basic mustache style tags for merging in values from the package.json. The following package.json values are supported:

• name
• version
• description
• author
• licence

The following additional values are also supported:

• file - path and filename of the current file relative to the current working directory.
• year - the current year.
• yearRange - the existing year and the current year as a range e.g. "2021-2024". Defaults to the current year if there is no existing year.

Example configuration:

{
    "banner": {
        "{src,test}/**/**.{ts,js}": [
            "/*!",
            " * {{ name }} v{{ version }}",
            " * {{ file }}",
            " * Copyright (c) {{ year }} {{ author }}",
            " * Released under the terms of the {{ license }} license",
            " */"
        ],
        "{src,test}/**/**.{yml,yaml}": [
            "# {{ name }} v{{ version }}",
            "# {{ file }}",
            "# Copyright (c) {{ year }} {{ author }}",
            "# Released under the terms of the {{ license }} license"
        ]
    }
}

CLI

The banner CLI is the easiest way to apply banner comments to files.

Usage: banner [options] [file/dir/glob...]

Generate a banner comment for file(s) and append it to the start of the file.

Options:
  -h, --help      Show CLI usage.
  -r, --remove    Remove existing banner comment from given file(s).
  -v, --verbose   Output additional information when writing to files.
  -w, --write     Edit files in-place. (Beware!)

API

You can also apply banner comments programmatically in typescript or javascript.

import { Banner } from '@marktuk/banner';

Banner.fromPackageJson().then((banner) =>
    banner.apply('{src,test}/**/**.{ts,js,yml,yaml}', { write: true })
);

Banner

Instances of the Banner class are used to add, update or remove a banner comments from the content of multiple files.

Constructors

new Banner(init)

new Banner(init): Banner

Creates an instance of the Banner class.

Parameters

| Parameter | Type | Description | | :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | init | object | An object with configuration options to initalise the Banner instance. | | init.data? | object | An object containing data to be merged in to the banner commenttemplate. Object keys should match the placeholdes in the template, and values can be either a string, number or a function expression that receives the previous value as a string and returnsa new value. | | init.templates | object | An object containing templates for generating banner comments. Eachkey should be a glob string used to match the template to a file, andeach value should be a template specified as an array of strings. |

Source

banner.ts:72

Methods

apply()

apply(pattern, options?): AsyncGenerator<[string, string], void, void>

Adds, updates or removes banner comments for all files that match a specified glob string pattern and optionally writes back to the files.

Parameters

| Parameter | Type | Description | | :------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | pattern | string | A valid glob pattern to find all files relative to the current workingdirectory to apply banner comments to. | | options? | object | An object for specifying options for how banner comments will be appliedto matching files. | | options.chunkSize? | number | Sets the amount of data in bytes to process per chunk. Thisshould not be set lower than the potential size of a bannercomment i.e. the comment needs to fit in a sigle chunk, otherwiseexisting comments may not be matched and updated.Default Value16384 (16 KiB) | | options.remove? | boolean | Specifies if banner comments should be removed.Default Valuefalse | | options.write? | boolean | Specifies whether to write back to the files.Default Valuefalse |

Returns

An asynchronous generator that yields a tuple containing a processed file path and chunk.

Source

banner.ts:128

fromPackageJson()

static fromPackageJson(): Promise<Banner>

Creates an instance of the Banner class configured using the nearest package.json.

Source

banner.ts:33

BannerTransform

Instances of the BannerTransform class are used to add, update or remove a banner comment from the content of a file. The class can be used in the following ways:

• As a transform stream, to process a readable stream and write the result to another stream.
• Using the asyncIterator() method to process an async iterable and return an async iterable with the result.
• Using the apply() method to process a single string and return the result.

Extends

• Transform

Constructors

new BannerTransform(template, options)

new BannerTransform(template, options?): BannerTransform

Creates an instance of the BannerTransform class.

Parameters

| Parameter | Type | Description | | :------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | template | string | The banner comment template specified as a string. The template caninclude placeholders using {{ key }} syntax for values specified in anobject passed to the options.data parameter. | | options? | object | An object for specifying options for how a banner comment will be appliedto the stream content. | | options.chunkSize? | number | Sets the amount of data in bytes the transform stream willprocess per chunk. This should not be set lower than thepotential size of a banner comment i.e. the comment needs to fitin a sigle chunk, otherwise the stream will fail to replace anexisting comment.Default Value16384 (16 KiB) | | options.data? | object | Optionally provide an object with values to replace placeholders in the banner comment template. Object keys should match the placeholdes in the template, and values can be either a string,number or a function expression that receives the previous value as a string and returns a new value. | | options.remove? | boolean | Specifies if the banner comment should be removed.Default Valuefalse |

Overrides

Transform.constructor

Source

transform.ts:64

Methods

apply()

apply(content): string

Applies the banner comment to the content of a file.

Parameters

| Parameter | Type | Description | | :-------- | :------- | :----------------------------------------------------- | | content | string | The content of the file provided as a single string. |

Returns

The content of the file with the banner comment added, updated or removed.

Source

transform.ts:159

asyncIterator()

asyncIterator(content): AsyncGenerator<string, void, unknown>

Asynchronously apply a banner comment to the content of a file, processing the file in chunks. The banner comment will only be added, updated or removed from the first chunk.

Parameters

| Parameter | Type | Description | | :-------- | :-------------------------------------- | :----------------------------------------------------------------------------------------- | | content | AsyncIterable<string | Buffer> | The content of the file provided as an async iterable that yields chunksof the file. |

Returns

An asynchronous generator that yields the content of the file with the banner comment added, updated or removed.

Source

transform.ts:140

Contributing

I created this tool mainly to use in my own projects, so I am not planning to actively develop it or add new features. If you want a new feature I would recommend creating a new issue to discuss it before you create a pull request.

I do plan to maintain the tool so if you find a bug please do create an issue. Pull requests to fix bugs are also welcome.

You are also free to fork this project and use the source code as you wish under the terms of the MIT No Attribution licence.

Licence

Copyright © 2023 Mark Tyrrell, all rights reserved.
Released under the terms of the MIT license.