@terascop/rotor

rotor

• rotor
  • Environment
  • Paradigm
  • Install dependencies
  • Lint and format with Biome
  • Test
  • Compile the CLI to a single-file executable
  • Package to dist/lib and publish to npm
  • Lib usage
  • CLI usage

Environment

We use Bun instead of Node.js (runtime) + npm (package manager)

This project was created using bun init in bun v1.1.20.

This was tested only on Linux.

Windows might be OK but is not an official target.

Paradigm

This project is written in TypeScript.

The style is deliberately procedural and functional, with little dependencies.

Install dependencies

bun install

Lint and format with Biome

We use Biome, not ESLint, not Prettier.

# just check :
bun run check
# alias for :
bunx biome check

# check and write safe fixes :
bun run lint
# alias for :
bunx biome check --write

Test

We use Bun's integrated testing feature, not Jest.

It is mostly compatible with Jest syntax.

bun test
# or :
bunx test --watch

Compile the CLI to a single-file executable

See Bun's doc.

Right now the generated bin is quite fat (94MB, gzips to 34MB), but Bun will probably improve this in the future.

It can still be convenient to distribute a single file with zero dependencies, as an alternative to a Docker image.

bun run compile
# alias for :
bun build ./cli.ts --compile --target=bun-linux-x64-modern --sourcemap --outfile ./dist/bin/rotor

See released binaries on the release page.

Package to dist/lib and publish to npm

It transpiles lib.ts to JS with separate .d.ts TypeScript definition files.

bun run bundle
# alias for :
rm -rf ./dist/lib/ \
  && bun build ./lib.ts --target=node --outdir ./dist/lib \
  && tsc --project ./tsconfig.lib.json \
  && cp ./index.d.ts ./dist/lib/

# then :
npm publish --access public

See on @terascop/rotor on npm.

Lib usage

⚠️ TO BE TESTED

npm i @terascop/rotor

import { rotate } from './lib'

await rotate(config)

See config spec in index.d.ts :

export type Pattern = string
export type Limit = number

export type TimeUnit = 'hours' | 'days' | 'weeks' | 'months' | 'years'

export interface Duration {
  unit: TimeUnit
  number: number
}

export interface Window {
  unit: TimeUnit
  sliding?: number | undefined
}

export interface Rule {
  name: string
  span: Duration | null
  limit: Limit
  window: Window | undefined
}

export interface Config {
  dir: string
  patterns: Pattern[]
  ignoreEmptyFiles: boolean
  rules: Rule[]
}

See config example in default.yaml.

See full signature in lib.ts :

/**
 * description: rotates files according to the configuration
 * @param {Date} [now=new Date()] - the reference date for the rotation, defaults to the current date
 * @param {Partial<typeof fsp>} [fspOverride] - overrides for fs.promises methods (readdir, stat, unlink)
 */
export const rotate = async (
  config: Config,
  dryRun = false,
  now: Date = new Date(),
  fspOverride: Partial<typeof fsp> = {},
): Promise<Results> => { ... }

CLI usage

See output of bun ./cli.ts --help :

Options:
      --version       Show version number                              [boolean]
  -p, --dir           Path to the directory containing the files to be rotated.
                      Defaults to config.dir                            [string]
  -i, --ignore-empty  Ignore empty files. Defaults to config.ignoreEmptyFiles
                                                                       [boolean]
      --patterns      Regular expression(s) to match filenames. Defaults to con
                      fig.patterns. Examples:

                      \b(?<unixtimestamp>\d{12,13})\b


                      \b(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})[- _T](?<h
                      our>\d{2})[- :h](?<minute>\d{2})[- :h](?<second>\d{2})[sZ
                      ]?\b

                      ^foobar.\b(?<unixtimestamp>\d{12,13})\b.db.gz.enc$
                                                                         [array]
  -c, --config        Path to config file                               [string]
  -d, --default       Use the default config (subject to change !)
                                                      [boolean] [default: false]
  -e, --example       Display an example config file                   [boolean]
  -t, --dry-run       Perform a dry run (opposite of --apply)
                                                      [boolean] [default: false]
  -a, --apply         Apply the deletions (opposite of --dry-run)
                                                      [boolean] [default: false]
  -s, --colors        Colorize the output             [boolean] [default: false]
  -o, --output        What to output to stdout
  [choices: "list", "summary", "silent", "config-JSON", "config-YAML"] [default:
                                                                         "list"]
      --help          Show help                                        [boolean]