@slimio/manifest v0.9.1
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