Hatcher

Registries toolbox & update notifications for your CLI

Inspired by the node package update-notifier.

Contents

• Contents
• Usage
  • Update Notifier
    • Simple
    • Comprehensive
    • Adding update notification to any CLI
    • How
  • Registries toolbox
• API
  • notifier = UpdateNotifier({ name, owner, registry, currentVersion, updateCheckInterval})
    • name
    • owner
    • registry
    • currentVersion
    • updateCheckInterval
  • notifier.checkForUpdates(configDir)
  • notifier.notify(command, overwrite)
    • command
    • overwrite
    • Custom message
  • Update
  • Registry Class
  • latestVersion(registryDomain, module, owner)
    • registryDomain
    • module
    • owner
    • return type
  • latestStableVersion(registryDomain, module, owner)
  • sortedVersions(registryDomain, module, owner)
    • registryDomain
    • module
    • owner
    • return type
  • parseURL(url)
    • url
    • return type
  • getRegistry(registryDomain)
    • registryDomain
    • return type
• Contributing

Usage

Update Notifier

Simple

import {
  NestLand,
  UpdateNotifier,
} from "https://x.nest.land/[email protected]/mod.ts";

const notifier = new UpdateNotifier({
  name: "denon",
  registry: NestLand,
  currentVersion: "0.1.2",
});

await notifier.checkForUpdates();
notifier.notify();

Comprehensive

import {
  Github,
  UpdateNotifier,
} from "https://x.nest.land/[email protected]/mod.ts";

const notifier = new UpdateNotifier({
  name: "denon", // module name
  owner: "denosaurs", // module owner, mandatory for registries like github
  registry: Github, // registry object
  currentVersion: "0.1.2",
  updateCheckInterval: 1000 * 60 * 60, // time interval between two checks, in milliseconds
});

const update = await notifier.checkForUpdates(); // undefined if there is no update available
console.log(update);
/** {
  current: "0.1.2",
  latest: "2.4.0",
  type: "major",
  name: "denon",
  owner: "denosaurs",
  registry: "raw.githubusercontent.com"
} */

notifier.notify("my command"); // displays the default notification with a custom command

Adding update notification to any CLI

Suppose denon does not use hatcher to notify its users of updates.

You can install denon with hatcher built-in !

If the install command is :

deno install --allow-read --allow-run --allow-write --allow-net -f -q --unstable https://deno.land/x/[email protected]/denon.ts

You can do:

deno install -A https://x.nest.land/[email protected]/hatcher.ts
hatcher --allow-read --allow-run --allow-write --allow-net -f -q --unstable https://deno.land/x/[email protected]/denon.ts

And voila ! You will be notified as soon as an update is available.

How

Whenever you initiate the update notifier and it's not within the interval threshold, it will asynchronously check with the specified registry for available updates, then persist the result. This prevents any impact on your module startup performance.

The first time the user runs your app, it will check for an update, and even if an update is available, it will wait the specified updateCheckInterval before notifying the user (one day by default). This is done to not be annoying to the user, but might surprise you as an implementer if you're testing whether it works. Check out example.ts to quickly test out hatcher and see how you can test that it works in your app.

deno run -A https://x.nest.land/[email protected]/example.ts

Registries toolbox

import {
  getLatestVersion,
  parseURL,
} from "https://x.nest.land/[email protected]/mod.ts";

const result = parseURL("https://deno.land/x/[email protected]/src/runner.ts");
/** {
  registry: "deno.land",
  name: "denon",
  version: "1.2.0",
  parsedURL: "https://deno.land/x/denon@${version}/src/runner.ts",
  relativePath: "src/runner.ts",
  owner: ""
} */

const latestVersion = await getLatestVersion("deno.land", "denon");
console.log(latestVersion); // 0.2.4

API

notifier = UpdateNotifier({ name, owner, registry, currentVersion, updateCheckInterval})

name

required

type: string

owner

required for raw.githubusercontent.com, denopkg.com

type: string

registry

required

type: Registry

currentVersion

required

type: string | semver.SemVer

updateCheckInterval

In milliseconds, defaults to one day.

type: number

notifier.checkForUpdates(configDir)

configDir is the directory where hatcher will save some information about your module.

Defaults to ~/.deno/hatcher

Returns an Update object if there is an update available, undefined otherwise.

notifier.notify(command, overwrite)

By default, will ask the user to visit the registry.

notifier.notify();

command

type: string

notifier.notify("my command");

overwrite

type: boolean

Will overwrite the body of the notification.

notifier.notify("My custom message", true);

Custom message

You can of course also display a fully customized message if an update is available.

const update = await notifier.checkForUpdates();
if (update) {
  console.log(`New update! ${update.latest}`);
}

Update

{
  latest:
  string;
  current:
  string;
  type:
  semver.ReleaseType | null; // "pre" | "major" | "premajor" | "minor" | "preminor" | "patch" | "prepatch" | "prerelease" | null
  name:
  string;
  owner:
  string;
  registry:
  string;
}

Registry Class

Supported registers for the time being:

You can add your own registers by adding them to registries.

import { registries } from "https://x.nest.land/[email protected]/mod.ts";

registries.push(myRegistry);

Your registry must implement the Registry object:

abstract class Registry {
  static domain: string;

  static async latestVersion(
    module: string,
    owner?: string,
  ): Promise<string | undefined>;

  static async latestStableVersion(
    module: string,
    owner?: string,
  ): Promise<string | undefined>;

  static async sortedVersions(
    module: string,
    owner?: string,
  ): Promise<string[]>;

  static parseURL(url: string): URLData;
}

latestVersion(registryDomain, module, owner)

Get latest version from supported registries

registryDomain

required

type: string

One of the supported registries domain.

module

required

type: string

owner

required for raw.githubusercontent.com, denopkg.com

type: string

return type

type: string

latestStableVersion(registryDomain, module, owner)

Same as latestVersion but get the latest stable version according to the SemVer rules.

sortedVersions(registryDomain, module, owner)

Get sorted versions from supported registries

registryDomain

required

type: string

One of the supported registries domain.

module

required

type: string

owner

required for raw.githubusercontent.com, denopkg.com

type: string

return type

type: string[]

parseURL(url)

Parse an URL from supported registries

url

required

type: string

return type

interface ProcessedURL {
  registry: string;
  name: string;
  owner: string;
  version: string;
  parsedURL: string;
  relativePath: string;
}

getRegistry(registryDomain)

Get registry object from web domain

registryDomain

required

type: string

return type

type: Registry

Contributing

All contributions are welcome! If you can think of a command or feature that might benefit nest.land, fork this repository and make a pull request from your branch with the additions. Make sure to use Conventional Commits

Contribution guide