jackspeak - npm Package Compare versions

Comparing version 2.0.0 to 2.0.1

dist/cjs/index.d.ts

 /// <reference types="node" />
 export type ConfigType = 'number' | 'string' | 'boolean';
 import { inspect, InspectOptions } from 'node:util';
-type ValidValue<T extends ConfigType, M extends boolean> = [T, M] extends [
-    'number',
-    true
-] ? number[] : [T, M] extends ['string', true] ? string[] : [T, M] extends ['boolean', true] ? boolean[] : [T, M] extends ['number', false] ? number : [T, M] extends ['string', false] ? string : [T, M] extends ['boolean', false] ? boolean : [T, M] extends ['string', boolean] ? string | string[] : [T, M] extends ['boolean', boolean] ? boolean | boolean[] : [T, M] extends ['number', boolean] ? number | number[] : [T, M] extends [ConfigType, false] ? string | number | boolean : [T, M] extends [ConfigType, true] ? string[] | number[] | boolean[] : string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Defines the type of value that is valid, given a config definition's
+ * {@link ConfigType} and boolean multiple setting
+ */
+export type ValidValue<T extends ConfigType, M extends boolean> = [
+    T,
+    M
+] extends ['number', true] ? number[] : [T, M] extends ['string', true] ? string[] : [T, M] extends ['boolean', true] ? boolean[] : [T, M] extends ['number', false] ? number : [T, M] extends ['string', false] ? string : [T, M] extends ['boolean', false] ? boolean : [T, M] extends ['string', boolean] ? string | string[] : [T, M] extends ['boolean', boolean] ? boolean | boolean[] : [T, M] extends ['number', boolean] ? number | number[] : [T, M] extends [ConfigType, false] ? string | number | boolean : [T, M] extends [ConfigType, true] ? string[] | number[] | boolean[] : string | number | boolean | string[] | number[] | boolean[];
+/**
+ * The meta information for a config option definition, when the
+ * type and multiple values can be inferred by the method being used
+ */
 export type ConfigOptionMeta<T extends ConfigType, M extends boolean> = {
@@ -20,9 +28,21 @@ default?: ValidValue<T, M> | undefined;
 });
+/**
+ * A set of {@link ConfigOptionMeta} fields, referenced by their longOption
+ * string values.
+ */
 export type ConfigMetaSet<T extends ConfigType, M extends boolean> = {
     [longOption: string]: ConfigOptionMeta<T, M>;
 };
-type ConfigSetFromMetaSet<T extends ConfigType, M extends boolean, S extends ConfigMetaSet<T, M>> = {
+/**
+ * Infer {@link ConfigSet} fields from a given {@link ConfigMetaSet}
+ */
+export type ConfigSetFromMetaSet<T extends ConfigType, M extends boolean, S extends ConfigMetaSet<T, M>> = {
     [longOption in keyof S]: ConfigOptionBase<T, M>;
 };
-type MultiType<M extends boolean> = M extends true ? {
+/**
+ * Fields that can be set on a {@link ConfigOptionBase} or
+ * {@link ConfigOptionMeta} based on whether or not the field is known to be
+ * multiple.
+ */
+export type MultiType<M extends boolean> = M extends true ? {
     multiple: true;
@@ -37,3 +57,6 @@ delim?: string | undefined;
 };
-type ConfigOptionBase<T extends ConfigType, M extends boolean> = {
+/**
+ * A config field definition, in its full representation.
+ */
+export type ConfigOptionBase<T extends ConfigType, M extends boolean> = {
     type: T;
@@ -46,12 +69,52 @@ short?: string | undefined;
 } & MultiType<M>;
-type ConfigSet = {
+/**
+ * A set of {@link ConfigOptionBase} objects, referenced by their longOption
+ * string values.
+ */
+export type ConfigSet = {
     [longOption: string]: ConfigOptionBase<ConfigType, boolean>;
 };
-type OptionsResults<T extends ConfigSet> = {
+/**
+ * The 'values' field returned by {@link Jack#parse}
+ */
+export type OptionsResults<T extends ConfigSet> = {
     [k in keyof T]?: T[k] extends ConfigOptionBase<'string', false> ? string : T[k] extends ConfigOptionBase<'string', true> ? string[] : T[k] extends ConfigOptionBase<'number', false> ? number : T[k] extends ConfigOptionBase<'number', true> ? number[] : T[k] extends ConfigOptionBase<'boolean', false> ? boolean : T[k] extends ConfigOptionBase<'boolean', true> ? boolean[] : never;
 };
-type Parsed<T extends ConfigSet> = {
+/**
+ * The object retured by {@link Jack#parse}
+ */
+export type Parsed<T extends ConfigSet> = {
     values: OptionsResults<T>;
     positionals: string[];
 };
+/**
+ * A row used when generating the {@link Jack#usage} string
+ */
+export interface Row {
+    left?: string;
+    text: string;
+    skipLine?: boolean;
+    type?: string;
+}
+/**
+ * A heading or description row used when generating the {@link Jack#usage}
+ * string
+ */
+export interface TextRow {
+    type: 'heading' | 'description';
+    text: string;
+    left?: '';
+    skipLine?: boolean;
+}
+/**
+ * Either a {@link TextRow} or a reference to a {@link ConfigOptionBase}
+ */
+export type UsageField = TextRow | {
+    type: 'config';
+    name: string;
+    value: ConfigOptionBase<ConfigType, boolean>;
+};
+/**
+ * Options provided to the {@link Jack} constructor
+ */
 export interface JackOptions {
@@ -97,7 +160,26 @@ /**
 }
+/**
+ * Class returned by the {@link jack} function and all configuration
+ * definition methods.  This is what gets chained together.
+ */
 export declare class Jack<C extends ConfigSet = {}> {
     #private;
     constructor(options?: JackOptions);
+    /**
+     * Parse a string of arguments, and return the resulting
+     * `{ values, positionals }` object.
+     *
+     * If an {@link JackOptions#envPrefix} is set, then it will read default
+     * values from the environment, and write the resulting values back
+     * to the environment as well.
+     */
     parse(args?: string[]): Parsed<C>;
+    /**
+     * Validate that any arbitrary object is a valid configuration `values`
+     * object.  Useful when loading config files or other sources.
+     */
     validate(o: any): asserts o is Parsed<C>['values'];
+    /**
+     * Add a heading to the usage output banner
+     */
     heading(text: string): Jack<C>;
@@ -138,3 +220,9 @@ /**
     addFields<F extends ConfigSet>(fields: F): Jack<C & F>;
+    /**
+     * Return the usage banner for the given configuration
+     */
     usage(): string;
+    /**
+     * Return the configuration options as a plain object
+     */
     toJSON(): {
@@ -151,6 +239,11 @@ [k: string]: {
     };
+    /**
+     * Custom printer for `util.inspect`
+     */
     [inspect.custom](_: number, options: InspectOptions): string;
 }
+/**
+ * Main entry point. Create and return a {@link Jack} object.
+ */
 export declare const jack: (options?: JackOptions) => Jack<{}>;
-export {};
 //# sourceMappingURL=index.d.ts.map

dist/cjs/index.js

@@ -217,2 +217,6 @@ "use strict";
 };
+/**
+ * Class returned by the {@link jack} function and all configuration
+ * definition methods.  This is what gets chained together.
+ */
 class Jack {
@@ -235,6 +239,14 @@ #configSet;
         // starts out as having an empty config set.  Then each method that adds
-        // fields returns `new Jack<C & { ...newConfigs }>()`
+        // fields returns `this as Jack<C & { ...newConfigs }>`
         this.#configSet = Object.create(null);
         this.#shorts = Object.create(null);
     }
+    /**
+     * Parse a string of arguments, and return the resulting
+     * `{ values, positionals }` object.
+     *
+     * If an {@link JackOptions#envPrefix} is set, then it will read default
+     * values from the environment, and write the resulting values back
+     * to the environment as well.
+     */
     parse(args = process.argv) {
@@ -344,2 +356,6 @@ if (args === process.argv) {
     }
+    /**
+     * Validate that any arbitrary object is a valid configuration `values`
+     * object.  Useful when loading config files or other sources.
+     */
     validate(o) {
@@ -371,2 +387,5 @@ if (!o || typeof o !== 'object') {
     }
+    /**
+     * Add a heading to the usage output banner
+     */
     heading(text) {
@@ -476,2 +495,5 @@ this.#fields.push({ type: 'heading', text });
     }
+    /**
+     * Return the usage banner for the given configuration
+     */
     usage() {
@@ -609,2 +631,5 @@ if (this.#usage)
     }
+    /**
+     * Return the configuration options as a plain object
+     */
     toJSON() {
@@ -624,2 +649,5 @@ return Object.fromEntries(Object.entries(this.#configSet).map(([field, def]) => [
     }
+    /**
+     * Custom printer for `util.inspect`
+     */
     [node_util_1.inspect.custom](_, options) {
@@ -640,4 +668,7 @@ return `Jack ${(0, node_util_1.inspect)(this.toJSON(), options)}`;
     .trim();
+/**
+ * Main entry point. Create and return a {@link Jack} object.
+ */
 const jack = (options = {}) => new Jack(options);
 exports.jack = jack;
 //# sourceMappingURL=index.js.map

dist/mjs/index.d.ts

 /// <reference types="node" />
 export type ConfigType = 'number' | 'string' | 'boolean';
 import { inspect, InspectOptions } from 'node:util';
-type ValidValue<T extends ConfigType, M extends boolean> = [T, M] extends [
-    'number',
-    true
-] ? number[] : [T, M] extends ['string', true] ? string[] : [T, M] extends ['boolean', true] ? boolean[] : [T, M] extends ['number', false] ? number : [T, M] extends ['string', false] ? string : [T, M] extends ['boolean', false] ? boolean : [T, M] extends ['string', boolean] ? string | string[] : [T, M] extends ['boolean', boolean] ? boolean | boolean[] : [T, M] extends ['number', boolean] ? number | number[] : [T, M] extends [ConfigType, false] ? string | number | boolean : [T, M] extends [ConfigType, true] ? string[] | number[] | boolean[] : string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Defines the type of value that is valid, given a config definition's
+ * {@link ConfigType} and boolean multiple setting
+ */
+export type ValidValue<T extends ConfigType, M extends boolean> = [
+    T,
+    M
+] extends ['number', true] ? number[] : [T, M] extends ['string', true] ? string[] : [T, M] extends ['boolean', true] ? boolean[] : [T, M] extends ['number', false] ? number : [T, M] extends ['string', false] ? string : [T, M] extends ['boolean', false] ? boolean : [T, M] extends ['string', boolean] ? string | string[] : [T, M] extends ['boolean', boolean] ? boolean | boolean[] : [T, M] extends ['number', boolean] ? number | number[] : [T, M] extends [ConfigType, false] ? string | number | boolean : [T, M] extends [ConfigType, true] ? string[] | number[] | boolean[] : string | number | boolean | string[] | number[] | boolean[];
+/**
+ * The meta information for a config option definition, when the
+ * type and multiple values can be inferred by the method being used
+ */
 export type ConfigOptionMeta<T extends ConfigType, M extends boolean> = {
@@ -20,9 +28,21 @@ default?: ValidValue<T, M> | undefined;
 });
+/**
+ * A set of {@link ConfigOptionMeta} fields, referenced by their longOption
+ * string values.
+ */
 export type ConfigMetaSet<T extends ConfigType, M extends boolean> = {
     [longOption: string]: ConfigOptionMeta<T, M>;
 };
-type ConfigSetFromMetaSet<T extends ConfigType, M extends boolean, S extends ConfigMetaSet<T, M>> = {
+/**
+ * Infer {@link ConfigSet} fields from a given {@link ConfigMetaSet}
+ */
+export type ConfigSetFromMetaSet<T extends ConfigType, M extends boolean, S extends ConfigMetaSet<T, M>> = {
     [longOption in keyof S]: ConfigOptionBase<T, M>;
 };
-type MultiType<M extends boolean> = M extends true ? {
+/**
+ * Fields that can be set on a {@link ConfigOptionBase} or
+ * {@link ConfigOptionMeta} based on whether or not the field is known to be
+ * multiple.
+ */
+export type MultiType<M extends boolean> = M extends true ? {
     multiple: true;
@@ -37,3 +57,6 @@ delim?: string | undefined;
 };
-type ConfigOptionBase<T extends ConfigType, M extends boolean> = {
+/**
+ * A config field definition, in its full representation.
+ */
+export type ConfigOptionBase<T extends ConfigType, M extends boolean> = {
     type: T;
@@ -46,12 +69,52 @@ short?: string | undefined;
 } & MultiType<M>;
-type ConfigSet = {
+/**
+ * A set of {@link ConfigOptionBase} objects, referenced by their longOption
+ * string values.
+ */
+export type ConfigSet = {
     [longOption: string]: ConfigOptionBase<ConfigType, boolean>;
 };
-type OptionsResults<T extends ConfigSet> = {
+/**
+ * The 'values' field returned by {@link Jack#parse}
+ */
+export type OptionsResults<T extends ConfigSet> = {
     [k in keyof T]?: T[k] extends ConfigOptionBase<'string', false> ? string : T[k] extends ConfigOptionBase<'string', true> ? string[] : T[k] extends ConfigOptionBase<'number', false> ? number : T[k] extends ConfigOptionBase<'number', true> ? number[] : T[k] extends ConfigOptionBase<'boolean', false> ? boolean : T[k] extends ConfigOptionBase<'boolean', true> ? boolean[] : never;
 };
-type Parsed<T extends ConfigSet> = {
+/**
+ * The object retured by {@link Jack#parse}
+ */
+export type Parsed<T extends ConfigSet> = {
     values: OptionsResults<T>;
     positionals: string[];
 };
+/**
+ * A row used when generating the {@link Jack#usage} string
+ */
+export interface Row {
+    left?: string;
+    text: string;
+    skipLine?: boolean;
+    type?: string;
+}
+/**
+ * A heading or description row used when generating the {@link Jack#usage}
+ * string
+ */
+export interface TextRow {
+    type: 'heading' | 'description';
+    text: string;
+    left?: '';
+    skipLine?: boolean;
+}
+/**
+ * Either a {@link TextRow} or a reference to a {@link ConfigOptionBase}
+ */
+export type UsageField = TextRow | {
+    type: 'config';
+    name: string;
+    value: ConfigOptionBase<ConfigType, boolean>;
+};
+/**
+ * Options provided to the {@link Jack} constructor
+ */
 export interface JackOptions {
@@ -97,7 +160,26 @@ /**
 }
+/**
+ * Class returned by the {@link jack} function and all configuration
+ * definition methods.  This is what gets chained together.
+ */
 export declare class Jack<C extends ConfigSet = {}> {
     #private;
     constructor(options?: JackOptions);
+    /**
+     * Parse a string of arguments, and return the resulting
+     * `{ values, positionals }` object.
+     *
+     * If an {@link JackOptions#envPrefix} is set, then it will read default
+     * values from the environment, and write the resulting values back
+     * to the environment as well.
+     */
     parse(args?: string[]): Parsed<C>;
+    /**
+     * Validate that any arbitrary object is a valid configuration `values`
+     * object.  Useful when loading config files or other sources.
+     */
     validate(o: any): asserts o is Parsed<C>['values'];
+    /**
+     * Add a heading to the usage output banner
+     */
     heading(text: string): Jack<C>;
@@ -138,3 +220,9 @@ /**
     addFields<F extends ConfigSet>(fields: F): Jack<C & F>;
+    /**
+     * Return the usage banner for the given configuration
+     */
     usage(): string;
+    /**
+     * Return the configuration options as a plain object
+     */
     toJSON(): {
@@ -151,6 +239,11 @@ [k: string]: {
     };
+    /**
+     * Custom printer for `util.inspect`
+     */
     [inspect.custom](_: number, options: InspectOptions): string;
 }
+/**
+ * Main entry point. Create and return a {@link Jack} object.
+ */
 export declare const jack: (options?: JackOptions) => Jack<{}>;
-export {};
 //# sourceMappingURL=index.d.ts.map

dist/mjs/index.js

@@ -211,2 +211,6 @@ import { inspect } from 'node:util';
 };
+/**
+ * Class returned by the {@link jack} function and all configuration
+ * definition methods.  This is what gets chained together.
+ */
 export class Jack {
@@ -229,6 +233,14 @@ #configSet;
         // starts out as having an empty config set.  Then each method that adds
-        // fields returns `new Jack<C & { ...newConfigs }>()`
+        // fields returns `this as Jack<C & { ...newConfigs }>`
         this.#configSet = Object.create(null);
         this.#shorts = Object.create(null);
     }
+    /**
+     * Parse a string of arguments, and return the resulting
+     * `{ values, positionals }` object.
+     *
+     * If an {@link JackOptions#envPrefix} is set, then it will read default
+     * values from the environment, and write the resulting values back
+     * to the environment as well.
+     */
     parse(args = process.argv) {
@@ -338,2 +350,6 @@ if (args === process.argv) {
     }
+    /**
+     * Validate that any arbitrary object is a valid configuration `values`
+     * object.  Useful when loading config files or other sources.
+     */
     validate(o) {
@@ -365,2 +381,5 @@ if (!o || typeof o !== 'object') {
     }
+    /**
+     * Add a heading to the usage output banner
+     */
     heading(text) {
@@ -470,2 +489,5 @@ this.#fields.push({ type: 'heading', text });
     }
+    /**
+     * Return the usage banner for the given configuration
+     */
     usage() {
@@ -603,2 +625,5 @@ if (this.#usage)
     }
+    /**
+     * Return the configuration options as a plain object
+     */
     toJSON() {
@@ -618,2 +643,5 @@ return Object.fromEntries(Object.entries(this.#configSet).map(([field, def]) => [
     }
+    /**
+     * Custom printer for `util.inspect`
+     */
     [inspect.custom](_, options) {
@@ -633,3 +661,6 @@ return `Jack ${inspect(this.toJSON(), options)}`;
     .trim();
+/**
+ * Main entry point. Create and return a {@link Jack} object.
+ */
 export const jack = (options = {}) => new Jack(options);
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "jackspeak",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A very strict and proper argument parser.",
@@ -5,0 +5,0 @@ "main": "./dist/cjs/index.js",

README.md

@@ -72,4 +72,10 @@ # jackspeak
 
-## `jack(options: JackOptions = {})`
+## `jack(options: JackOptions = {}) => Jack`
 
+Returns a `Jack` object that can be used to chain and add
+field definitions.  The other methods (apart from `validate()`,
+`parse()`, and `usage()` obviously) return the same Jack object,
+updated with the new types, so they can be chained together as
+shown in the code examples.
+
 Options:
@@ -200,3 +206,3 @@
 
-### `Jack.usage()`
+### `Jack.usage(): string`
 
@@ -203,0 +209,0 @@ Returns the compiled `usage` string, with all option descriptions

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

198479

increased by7.22%

Lines of code

1877

increased by15.37%

Number of lines in readme file

318

increased by1.92%

Number of medium supply chain risk alerts

0

decreased by-100%

No dependency changes