@gunshi/plugin-global 0.27.0-alpha.8 → 0.27.0-beta.0

package/README.md

@@ -1,5 +1,9 @@
 # @gunshi/plugin-global
 
+[![Version][npm-version-src]][npm-version-href]
+[![InstallSize][install-size-src]][install-size-src]
+[![JSR][jsr-src]][jsr-href]
+
 > global options plugin for gunshi.
 
 This plugin provides standard global options (`--help` and `--version`) for all commands in your CLI application. It's installed by default in gunshi, ensuring consistent behavior across all CLI applications.
@@ -87,6 +91,13 @@ When using the global options plugin, your command context is extended via `ctx.
 
 Available extensions:
 
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!NOTE]
+> The `Awaitable<T>` type used in the method signatures below is equivalent to `T | Promise<T>`, meaning the methods can return either a value directly or a Promise that resolves to that value.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
 - **`showVersion(): string`**: Display the application version. Returns `'unknown'` if no version is specified in the CLI configuration.
 
 - **`showHeader(): Awaitable<string | undefined>`**: Display the application header. Returns `undefined` if no `renderHeader` function is provided in the CLI configuration.
@@ -98,14 +109,14 @@ Available extensions:
 ### Usage Example
 
 ```ts
-import global, { pluginId } from '@gunshi/plugin-global'
+import global, { pluginId as globalId } from '@gunshi/plugin-global'
 import { cli } from 'gunshi'
 
 const command = {
   name: 'deploy',
   run: async ctx => {
-    // Access globals extensions
-    const { showVersion, showHeader } = ctx.extensions[pluginId]
+    // Access global extensions
+    const { showVersion, showHeader } = ctx.extensions[globalId]
 
     // Manually show version if needed
     console.log(`Deploying with CLI version: ${showVersion()}`)
@@ -143,3 +154,11 @@ See the [API References](./docs/index.md)
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-global?style=flat
+[npm-version-href]: https://npmjs.com/package/@gunshi/plugin-global@alpha
+[jsr-src]: https://jsr.io/badges/@gunshi/plugin-global
+[jsr-href]: https://jsr.io/@gunshi/plugin-global
+[install-size-src]: https://pkg-size.dev/badge/install/39632

package/lib/index.d.ts

@@ -6,25 +6,29 @@ import { Awaitable, PluginWithExtension } from "@gunshi/plugin";
  * Extended command context which provides utilities via global options plugin.
  * These utilities are available via `CommandContext.extensions['g:global']`.
  */
-interface GlobalCommandContext {
+interface GlobalExtension {
   /**
    * Show the version of the application. if `--version` option is specified, it will print the version to the console.
+   *
    * @returns The version of the application, or `unknown` if the version is not specified.
    */
   showVersion: () => string;
   /**
    * Show the header of the application.
+   *
    * @returns The header of the application, or `undefined` if the `renderHeader` is not specified.
    */
   showHeader: () => Awaitable<string | undefined>;
   /**
    * Show the usage of the application. if `--help` option is specified, it will print the usage to the console.
+   *
    * @returns The usage of the application, or `undefined` if the `renderUsage` is not specified.
    */
   showUsage: () => Awaitable<string | undefined>;
   /**
    * Show validation errors. This is called when argument validation fails.
-   * @param error The aggregate error containing validation failures
+   *
+   * @param error - The aggregate error containing validation failures
    * @returns The rendered error message, or `undefined` if `renderValidationErrors` is null
    */
   showValidationErrors: (error: AggregateError) => Awaitable<string | undefined>;
@@ -40,13 +44,11 @@ declare const PLUGIN_PREFIX = "g";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
 //#endregion
 //#region ../shared/src/types.d.ts
+
 /**
  * Generate a namespaced key.
  */
 type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
-/**
- * Command i18n built-in arguments keys.
- */
 //#endregion
 //#region src/types.d.ts
 /**
@@ -61,7 +63,9 @@ type PluginId = typeof pluginId;
 //#region src/index.d.ts
 /**
  * global options plugin
+ *
+ * @returns A defined plugin as global options
  */
-declare function global(): PluginWithExtension<GlobalCommandContext>;
+declare function global(): PluginWithExtension<GlobalExtension>;
 //#endregion
-export { GlobalCommandContext, PluginId, global as default, pluginId };
+export { type GlobalExtension, PluginId, global as default, pluginId };

package/lib/index.js

@@ -26,6 +26,14 @@ const COMMON_ARGS = {
 
 //#endregion
 //#region ../shared/src/utils.ts
+/**
+* Generate a namespaced key for a plugin.
+*
+* @typeParam K - The type of the plugin id to generate a namespaced key for.
+*
+* @param id - A plugin id to generate a namespaced key.
+* @returns A namespaced key for the plugin.
+*/
 function namespacedId(id) {
 	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
 }
@@ -41,6 +49,9 @@ const pluginId = namespacedId("global");
 //#region src/decorator.ts
 /**
 * Decorator function to extend the command with global options.
+*
+* @param baseRunner - The base command runner
+* @returns A command decorator that adds global options handling
 */
 const decorator = (baseRunner) => async (ctx) => {
 	const { values, validationError, extensions: { [pluginId]: { showVersion, showHeader, showUsage, showValidationErrors } } } = ctx;
@@ -63,6 +74,12 @@ var decorator_default = decorator;
 
 //#endregion
 //#region src/extension.ts
+/**
+* Extends the command context for global options plugin.
+*
+* @param ctx - The {@linkcode CommandContextCore | command context} core
+* @returns An {@linkcode GlobalExtension} of global options plugin
+*/
 function extension(ctx) {
 	return {
 		showVersion: () => {
@@ -105,6 +122,8 @@ function extension(ctx) {
 //#region src/index.ts
 /**
 * global options plugin
+*
+* @returns A defined plugin as global options
 */
 function global() {
 	return plugin({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-global",
   "description": "global options plugin for gunshi",
-  "version": "0.27.0-alpha.8",
+  "version": "0.27.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,22 +51,22 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.27.0-alpha.8"
+    "@gunshi/plugin": "0.27.0-beta.0"
   },
   "devDependencies": {
-    "deno": "^2.4.0",
+    "deno": "^2.5.4",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
-    "publint": "^0.3.12",
-    "tsdown": "^0.12.9",
-    "typedoc": "^0.28.7",
-    "typedoc-plugin-markdown": "^4.7.0",
-    "@gunshi/shared": "0.27.0-alpha.8"
+    "publint": "^0.3.14",
+    "tsdown": "^0.15.6",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "@gunshi/shared": "0.27.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",
     "build:docs": "typedoc --excludeInternal",
     "lint:jsr": "jsr publish --dry-run --allow-dirty",
-    "typecheck:deno": "deno check ./src"
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
   }
 }