argsclopts - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

CHANGELOG.md

@@ -10,6 +10,12 @@ # Changelog
 
-## [v1.0.1](https://github.com/bcomnes/argsclopts/compare/v1.0.0...v1.0.1)
+## [v1.0.2](https://github.com/bcomnes/argsclopts/compare/v1.0.1...v1.0.2)
 
 ### Commits
 
+- Improve docs, finalize api [`98e74af`](https://github.com/bcomnes/argsclopts/commit/98e74af5ef161f1868362bb912bd6e4fe9bd1f21)
+
+## [v1.0.1](https://github.com/bcomnes/argsclopts/compare/v1.0.0...v1.0.1) - 2023-12-26
+
+### Commits
+
 - Fix type exports [`124b00f`](https://github.com/bcomnes/argsclopts/commit/124b00fb1ca9af4eca5b20579744a563845cf48e)
@@ -16,0 +22,0 @@ - Fix matrix [`1373c20`](https://github.com/bcomnes/argsclopts/commit/1373c200db7e8ebb50d49b3a0f2adc366f307a2b)

index.d.ts

@@ -6,6 +6,6 @@ export function usage(options: ArgscloptsParseArgsOptionsConfig): string;
 }>;
-export function header({ pkgPath, name, usageFn, exampleFn }: {
+export function header({ pkgPath, name, headerFn, exampleFn }: {
     pkgPath: string;
     name?: string | undefined;
-    usageFn?: FormatterFunction | undefined;
+    headerFn?: FormatterFunction | undefined;
     exampleFn?: FormatterFunction | undefined;
@@ -19,3 +19,3 @@ }): Promise<string>;
 }): Promise<string>;
-export function formatHelpText({ options, pkgPath, name, version, footerFn, usageFn, exampleFn }: {
+export function formatHelpText({ options, pkgPath, name, version, footerFn, headerFn, exampleFn }: {
     pkgPath: string;
@@ -25,7 +25,7 @@ options: ArgscloptsParseArgsOptionsConfig;
     version?: string | undefined;
-    usageFn?: FormatterFunction | undefined;
+    headerFn?: FormatterFunction | undefined;
     exampleFn?: FormatterFunction | undefined;
     footerFn?: FormatterFunction | undefined;
 }): Promise<string>;
-export function printHelpText({ options, pkgPath, name, version, footerFn, usageFn, exampleFn }: {
+export function printHelpText({ options, pkgPath, name, version, footerFn, headerFn, exampleFn }: {
     pkgPath: string;
@@ -35,3 +35,3 @@ options: ArgscloptsParseArgsOptionsConfig;
     version?: string | undefined;
-    usageFn?: FormatterFunction | undefined;
+    headerFn?: FormatterFunction | undefined;
     exampleFn?: FormatterFunction | undefined;
@@ -38,0 +38,0 @@ footerFn?: FormatterFunction | undefined;

index.js

@@ -86,3 +86,3 @@ import { readFile } from 'node:fs/promises'
  * @param {string} [params.name] - The name to be used in the header. If not provided, it's extracted from the package file at 'pkgPath'.
- * @param {FormatterFunction} [params.usageFn] - A function that returns the usage string.
+ * @param {FormatterFunction} [params.headerFn] - A function that returns the usage string.
  * @param {FormatterFunction} [params.exampleFn] - A function that returns an example string.
@@ -99,5 +99,4 @@ * @returns {Promise<string>} - A promise that resolves to the constructed header string.
   name,
-  usageFn = ({ name }) => `Usage: ${name} [options]\n`,
+  headerFn = ({ name }) => `Usage: ${name} [options]\n`,
   exampleFn = ({ name }) => indent + `Example: ${name}\n`
-
 }) {
@@ -114,3 +113,3 @@ let pkg
 
-  const header = [usageFn({ name: pkgName }), exampleFn({ name: pkgName })].join('\n')
+  const header = [headerFn({ name: pkgName }), exampleFn({ name: pkgName })].join('\n')
 
@@ -163,3 +162,3 @@ return header
  * @param {string} [params.version] - The bin version
- * @param {FormatterFunction} [params.usageFn] - A function that returns the usage string.
+ * @param {FormatterFunction} [params.headerFn] - A function that returns the usage string.
  * @param {FormatterFunction} [params.exampleFn] - A function that returns an example string.
@@ -178,7 +177,7 @@ * @param {FormatterFunction} [params.footerFn] - A function that returns the footer string.
   footerFn,
-  usageFn,
+  headerFn,
   exampleFn
 }) {
   const helpText = [
-    await header({ pkgPath, name, usageFn, exampleFn }),
+    await header({ pkgPath, name, headerFn, exampleFn }),
     usage(options),
@@ -199,3 +198,3 @@ await footer({ pkgPath, name, version, footerFn })
  * @param {string} [params.version] - The bin version
- * @param {FormatterFunction} [params.usageFn] - A function that returns the usage string.
+ * @param {FormatterFunction} [params.headerFn] - A function that returns the usage string.
  * @param {FormatterFunction} [params.exampleFn] - A function that returns an example string.
@@ -213,7 +212,7 @@ * @param {FormatterFunction} [params.footerFn] - A function that returns the footer string.
   footerFn,
-  usageFn,
+  headerFn,
   exampleFn
 }) {
   const helpText = [
-    await header({ pkgPath, name, usageFn, exampleFn }),
+    await header({ pkgPath, name, headerFn, exampleFn }),
     usage(options),
@@ -220,0 +219,0 @@ await footer({ pkgPath, name, version, footerFn })

package.json

 {
   "name": "argsclopts",
   "description": "cliclopts but for Node.js parseArgs",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "author": "Bret Comnes <[e-mail]> (https://bret.io)",
@@ -6,0 +6,0 @@ "bugs": {

README.md

@@ -18,6 +18,10 @@ # argsclopts
 ``` js
-import { formatHelpText, printHelpText } from 'argsclopts'
+import { printHelpText } from 'argsclopts'
 import { join } from 'node:path'
 import { parseArgs } from 'node:util'
 
+/**
+ * @typedef {import('argsclopts').ArgscloptsParseArgsOptionsConfig} ArgscloptsParseArgsOptionsConfig
+ */
+
 const pkgPath = join(import.meta.dirname, 'package.json')
@@ -57,7 +61,51 @@
 const { values } = parseArgs({ args, options })
+console.log(values)
 // { foo: true, bar: 'b' }
 ```
 
+## API
+
+### `import { formatHelpText, printHelpText, usage, header, footer } from 'argsclopts'`
+
+You can import `formatHelpText`, `printHelpText`, `usage`, `header`, `footer` from `argsclopts`.
+s
+### `helpText = formatHelpText({ options, [pkgPath], [name], [version], [footerFn], [headerFn], [exampleFn]})`
+
+Generate the `helptText` string. Requires passing in an `options` object that you provide to [`parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig), with one additional field per flag: `help`. You should also provide `pkgPath` (a resolved path the `package.json`) so that a bin name and version can be resolved. Otherwise, pass in a `name` and `version` to override any resolved data from `pkgPath`. If both  `name` and `version` are provided, a `pkgPath` is required. The `headerFn`, and `exampleFn` can be used to override the header text and the `footerFn` can be used to override the footer text.
+
+An example `options` object might look like this:
+
+```js
+const options = {
+  foo: {
+    type: 'boolean',
+    short: 'f',
+    help: 'A foo flag thats a boolean'
+  },
+  bar: {
+    type: 'string',
+    help: 'A bar flag thats a string'
+  }
+}
+```
+
+
+### `void printHelpText({ options, [pkgPath], [name], [version], [footerFn], [headerFn], [exampleFn]})`
+
+Exactly the same as `formatHelpText` except it uses `console.log` to print the text for you. Returns nothing.
+
+### `usageText = usage(options)`
+
+Generate just the usage string with a given `options` object.
+
+### `headerText = header({ [pkgPath], [name], [headerFn], [exampleFn] })
+
+Generate the headerText only. Pass in either a `pkgPath` string path to the `package.json` of the bin you are printing for, or a `name`. The `headerFn` and `exampleFn` allow you to override the header text that is generated. Each function receilves an object with a `name` key.
+
+### `footerText = footer({ [pkgPath], [name], [version], [footerFn] })`
+
+Generate the footerText only. Pass in either a `pkgPath` string path to the `package.json` of the bin you are printing for, or a `name` and/or `version`. The `footerFn` lets you override the footer text template and receives an object with a `name` and `version` key.
+
 ## License
 
 MIT

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24617

increased by11.47%

Number of lines in readme file

110

increased by77.42%

No dependency changes