huzma
v0.6.2
Published
A manifest format for browser-based package managers
Downloads
23
Maintainers
Readme
بسم الله الرحمن الرحيم
Huzma 📦
A manifest format for browser-based package managers
Huzma (the Arabic word for package, pronounced like this, spelt in Arabic حزمة) is a manifest format for browser-based package managers. This library is a Javascript implementation of the Huzma manifest format which includes:
Various functions, constants, and types to aid in creating and validating huzma manifests.
A command line interface to ease automation.
Originally made to import game mods into the Zakhaarif Launcher, this format takes inspiration from Node's package.json and Rust's cargo.toml.
Installation
npm i huzma
Specification
A huzma is a json file that has the file extension .huzma.json
and includes these keys:
⚠️ Required
schema
: an integer value of1
or2
, indicating which huzma version is used.name
: a string naming package.version
: a vaild semver (semantic version) string, indicating the version of package. Implementation provided by small-semver package.
✅ Optional
files
: an array of strings or objects indicating files that should be cached on disk if possible (viaCache API
,IndexedDB
, etc.). Objects must include a string value atname
field and an optional integer value atbytes
field and invalidation (string) atinvalidation
field.If a string value is provided it indicates the relative url of a file. If an object value is provided the
name
field repersents the relative url of a file, theinvalidation
field repersents how file should be diffed on package update, and thebytes
field repersents uncompressed size of file in bytes.All File urls must be relative to huzma manifest and cannot be an absolute url or start with
../
.Example:
{ "files": [ "index.js", "./index.js", "assets/cat.png", {"name": "assets/doggo.png"}, {"name": "styles/style.css", "bytes": 1234}, { "name": "multi-thread.wasm", "invalidation": "purge" }, { "name": "config.json", "invalidation": "url-diff", "bytes": 10540 } ] }
entry
: a url relative to huzma manifest that denotes an entry script (cannot be an absolute url or start with../
.). This communicates to package managers which file to import in order to execute code included in package.invalidation
: specify the default invalidation strategy for all files mentioned infiles
field.description
: a string that describes package.authors
: an array of objects repersenting project maintainers / main contributors. Object must include a string value atname
field, and optionally can provide an email value atemail
field and url (absolute) for aturl
field.Example:
{ "authors": [ {"name": "moomoolive"}, { "name": "milk_farmer", "email": "[email protected]" }, { "name": "pure_lactose", "email": "[email protected]", "url": "https://whatsinyourmilk.milk" } ] }
logoUrl
: a relative or absolute url to a picture that repersents package. Examples:https://yo-mamas.house/logo.png
,./silly-logo.jpg
, etc.keywords
: an array of string tags that describe package. Examples:penguins
,kitties
,html-parser
, etc.license
: a string denoting license granted to package user. Examples:MIT
,GPL-3
,Apache-2
,My-Own-Cool-License
, etc.repo
: an object representing package's code repository, with an optional string value attype
field and url aturl
field.Example:
{ "repo": { "type": "git", "url": "https://github.com/moomoolive/huzma" } }
homepageUrl
: absolute url to package website. Example:https://www.nexusmods.com/my-amazing-mod-homepage
permissions
: an array of strings or objects with a string value atkey
field and an array of strings atvalue
field. A string value (i.e"permission"
) is equivalent to an object with a string value atkey
field and an empty array atvalue
field (i.e{ "key": "permission", "value": [] }
).It is up to package managers to implement a concrete set of permissions.
Example:
{ "permissions": [ "permission1", {"key": "permission2", "value": []}, {"key": "permission3", "value": ["value1"]}, {"key": "permission3", "value": ["value1", "value2"]}, ] }
metadata
: an object of arbitrary key & value pairs, where values are strings. Denotes specific information a particular package manager may want to know about package. Works similar to http headers.Example:
{ "metadata": { "is-extension": "true", "pkg-manager-x-key": "key-exists", "created": "100003231414", "updated": "100003431414" } }
Invalidations
If a new version of a package is released, package managers will need to update the cached files of said package. Providing an invalidation strategy for a file(s) hints to package managers how to cache files.
Here are a list of strategies that may be provided:
url-diff
: file should only be cached if file with same url does not exist in package manager cache. Otherwise, file should not be cached.purge
: file should be recached on every new package version, regardless if a file with same url exists in package manager cache. By default theentry
file of a huzma manifest uses this strategy if it is found infiles
.default
: let package manager decide.
Command Line Tools
This package comes bundled with cli commands to help create huzem (plural for huzma). All commands can be programmatically invoked from as well. Package must be installed to invoke commands.
npx huzma-init
Initialize a huzma config file - a configuration file which is used by other commands in this package.
Options:
path
: a path where huzma config file should be created, must end withjs
ormjs
extension. Defaults tohuzma.config.mjs
.CLI:
npx huzma-init --path huzma.config.mjs
JS:
import {initHuzma} from "huzma/dist/cli.js" await initHuzma({path: "huzma.config.mjs"})
template
: available templates includezakhaarif
. Defaults to empty string.CLI:
npx huzma-init --template zakhaarif
JS:
import {initHuzma} from "huzma/dist/cli.js" await initHuzma({template: "zakhaarif"})
npx huzma-create
Create a huzma manifest.
Options:
buildDir
: ⚠️ required, directory that includes all package files.CLI:
npx huzma-create --buildDir dist
JS:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({buildDir: "dist"})
outFile
: the full path with the generated huzma manifest should be written to. Path must end with.huzma.json
. Defaults tobuildDir
+default.huzma.json
.CLI:
npx huzma-create --outFile dist/default.huzma.json
js:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({outFile: "dist/default.huzma.json"})
configFileName
: path to huzma config file, path must end withjs
ormjs
. Can be generated vianpx huzma-init
command. Defaults tohuzma.config.mjs
CLI:
npx huzma-create --configFileName huzma.config.mjs
JS:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({configFileName: "huzma.config.mjs"})
packageJsonPath
: Path to package json from which to auto-fill missing values from. SeedisablePackageJsonFill
for more details. Defaults topackage.json
CLI:
npx huzma-create --packageJsonPath package.json
JS:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({packageJsonPath: "package.json"})
disablePackageJsonFill
: Whether missing values not found in config file & inline config should be autofilled from package json. Values in package json are given a lower precedent than values found in config file or inline config. Setting flag disables auto-fill. To set path of package json set thepackageJsonPath
argument. Values that can be auto-filled frompackage.json
include:name
version
description
keywords
license
repository
: maps to huzma'srepo
field.contributors
: maps to huzma'sauthors
field.homepage
: maps to huzma'shomepageUrl
field.
CLI:
npx huzma-create --disablePackageJsonFill
JS:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({disablePackageJsonFill: true})
inlineConfigFile
: provide an inline config, which takes precedent over config file. Defaults to null. Cannot be used from cli.JS:
import {createHuzma} from "huzma/dist/cli.js" await createHuzma({ inlineConfigFile: { name: "my-huzma", version: "0.1.0" // ...rest of config } })