Manifest

This package was created to manage the manifest file of SlimIO projects. The manifest is useful when we need to describe specific behaviors and settings in our internals tools or to our global product. Some examples are:

• To create Addon archive the right way with the right parameters
• To the CLI to known the current addon dependencies (like npm).
• To disable given psp warnings (like eslint when you disable a rule).

Some might bring the question of why creating a dedicated manifest. The answer is simple: We did not want to add more keys and complexity to the package.json and bring a clean concern separation.

⚠️ This package read and write with Synchronous Node.js API. This package has been designed to be used as a tool or at runtime.

Requirements

• Node.js v12 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/manifest
# or
$ yarn add @slimio/manifest

Usage example

Open local manifest. The default manifest name is slimio.toml !

name = "yourProject"
version = "1.0.0"
type = "Package"

Then, use the package manifest to open the manifest (located in the current working dir).

const Manifest = require("@slimio/manifest");

const manifest = Manifest.open();
console.log(`name => ${manifest.name}`);

Available Types

| name | description | | --- | --- | | Addon | Describe a SlimIO Addon | | NAPI | A Node.js low-level binding in C or C++ with the new N-API | | CLI | A command line interface project | | Package | A classical npm/Node.js package | | Service | A web API | | Degraded | A project that doesn't match classical SlimIO policies like the eslint-config one |

API

Following methods are members of Manifest class. Some types are described in the TypeScript namespace as follow:

declare namespace Manifest {
    type Type = "Addon" | "NAPI" | "CLI" | "Package" | "Service" | "Degraded";
    type Platform = "Any" | "Windows" | "Unix";

    interface psp {
        npmrc: boolean;
        jsdoc: boolean;
        disabled_dependency: string[];
        exclude: string[];
    }

    interface Documentation {
        include: string[];
        port: number;
    }

    interface Dependencies {
        [name: string]: string;
    }

    interface Notes {
        [name: string]: string;
    }

    interface Payload {
        name: string;
        version: string;
        type: Type;
        required_core?: string;
        org?: string;
        dependencies?: Dependencies;
        platform?: Platform;
        psp?: psp;
        doc?: Documentation;
        notes?: Notes;
    }
}

⚠️ Only "Addon" manifests can have dependencies.

Create a new manifest at given filePath (The default value is equal to Manifest.DEFAULT_FILE). The manifest file must not exist, else the method will throw an Error.

const { strictEqual } = require("assert");
const { existsSync } = require("fs");

const Manifest = require("@slimio/manifest");

const manifest = Manifest.create({
    name: "project",
    version: "1.0.0",
    type: "NAPI"
});
strictEqual(existsSync(Manifest.DEFAULT_FILE), true);
console.log(manifest.toJSON());

Write a Manifest Object on the disk.

const Manifest = require("@slimio/manifest");

const manifest = Manifest.open();
// Do your work here... update manifest

Manifest.writeOnDisk(manifest);

Read and parse local .toml manifest file. The method return a complete Manifest Object (it will throw if something is wrong). The default value for filePath will be Manifest.DEFAULT_FILE.

const Manifest = require("@slimio/manifest");

const manifest = Manifest.open();
console.log(manifest.toJSON());

Return the Manifest Object as a JavaScript object (JSON compatible).

const Manifest = require("@slimio/manifest");

const manifest = Manifest.open();
console.log(manifest.toJSON());
console.log(JSON.stringify(manifest));

Getters

The Manifest Object is mostly composed of getters:

class Manifest {
    readonly name: string;
    readonly version: string;
    readonly type: Manifest.Type;
    readonly dependencies: Manifest.Dependencies;
    readonly doc: Manifest.Documentation;
    readonly psp: Manifest.psp;
    readonly notes: Manifest.Notes;
    readonly org: string | null;
    readonly required_core: string | null;
    readonly platform: Manifest.Platform;
}

Properties

following properties are static.

const { join } = require("path");

Manifest.DEFAULT_FILE = join(process.cwd(), "slimio.toml");

Readonly Sets of available string types.

Manifest.TYPES = Object.freeze(new Set(["Addon", "NAPI", "CLI", "Package", "Service"]));

Default documentation port (equal to 2000 by default).

Dependencies

|Name|Refactoring|Security Risk|Usage| |---|---|---|---| |@iarna/toml|Minor|Low|Parse and read .toml file| |@slimio/arg-checker|Minor|Low|Argument Checker| |@slimio/is|Minor|Low|JavaScript Type checker| |@slimio/immutable|Minor|Low|Immutable utils| |lodash.clonedeep|Minor|Low|Clone deep an Object| |semver|⚠️Major|Low|Semver parser/utilities for node|

License

MIT