README.md

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.

static create(payload: Manifest.Payload, filePath?: string): Manifest

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());

static writeOnDisk(manifest: Manifest, filePath?: string): void

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);

static open(filePath?: string): 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());

toJSON(): Manifest.Payload

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.

Manifest.DEFAULT_FILE

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

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

Manifest.TYPES

Readonly Sets of available string types.

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

Manifest.DEFAULT_DOC_PORT

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