@nuogz/pangu

盘古，统一初始化常用库的基石库
Pangu, the cornerstone library for unified initialising of common usage

警告：
尽管该库的代码目前处于公开状态，但该库目前仅为我个人使用。所有功能与设计均基于我的日常使用需求。
由于我个人精力和时间有限，无法对该库的代码和文档作出任何质量保证，也无法对过期的版本提供任何支持。而对于最新版本，也只能最低限度的慢速的支持。
因此不推荐任何用户使用该库，除非对其代码有充分的了解和信心。

Warning:
Although the code for this library is currently in a public state, the library is currently for my personal use only. All functionality and design is based on my daily usage requirements.
Due to my limited personal energy and time, I cannot provide any quality assurance for the code and documentation of this library, nor can I provide any support for outdated versions. I can't provide any support for outdated versions, and I can only support the latest version at a slow minimum.
Therefore, I do not recommend any user to use this library unless they have full knowledge and confidence in its code.

Most of the English content in this document was generated by machine translation (if available).

• @nuogz/pangu
  • 初始化配置
    • 初始化配置说明符
      • 示例：启用组件
      • 示例：传递默认的组件参数
      • 示例：传递具名的组件参数
      • 示例：组件别名
      • 示例：组件空间
      • 示例：综合应用
  • 传递初始化配置
    • 优先级
    • 定位
    • 导入语法的内联参数
    • 环境变量NENV_PANGU
    • 命令行（WIP）
  • 组件
    • 环境变量
      • NENV_PANGU
      • NENV_PANGU_DIR
    • 前置组件
      • 国际化i18n
        • NENV_I18N_LOCALE赋值优先级
        • NENV_I18N_FORMAT赋值优先级
        • 导出变量
      • 工作目录dir
        • 赋值优先级
        • 特殊插入值
        • 导出变量
      • 项目信息package
        • 赋值优先级
        • 导出变量
    • 主要组件
      • 命令行command（WIP）
        • 导出变量
      • 配置config
        • 导出变量
      • 日志log
        • 导出变量
    • 对其他库或功能的初始化
      • 进程process
        • 导出变量
      • 时间日期day
        • 导出变量
    • 导出相关库
      • Hades
      • Poseidon
      • Commander

初始化配置

• 盘古会根据不同的初始化配置，异步导入并初始化不同的库
• 如果不传递初始化配置，盘古不会加载任何东西
• 盘古是希望开箱即用，让默认配置尽量符合我的使用习惯的。因此会设定不少默认值
• 通过import或环境变量传递初始化配置时，需按照初始化配置说明符的格式进行传递

初始化配置说明符

• 说明符外层的格式遵循URL规范中的query部分，使用new URL()进行解析
• short，表示启用该组件。short是启用的组件名或其缩写。
  • 启用多个组件使用&连接
  • 如果short后带有第一个:，表示设置组件别名。通过设置别名可以让盘古初始化多个相同类型的组件
  • 如果short后带有第二个:，表示设置环境空间。高级组件可能会依赖其他前置的基础组件。通过设置空间可以指定组件使用相应的前置组件
  • 如果short前带有?，表示只返回已启用的同名组件，不会主动初始化
  • 如果short后带有=，表示传递组件参数param
    • 传递多个param使用,连接
    • param，组件参数。
  • 如果short后带有.，表示传递一个具名参数paramNamed
    • paramNamed，组件具名参数。多个paramNamed使用,连接
    • 具名参数使用方式和优先级，由组件自行决定
    • 单独传递具名参数，是不会启用组件的。必须传递一个非具名的short才算启用
• 说明符中所有涉及的特殊符号，均可以使用\逃逸

示例：启用组件

• config
  • 启用配置组件
• config&log
  • 启用配置组件
  • 启用日志组件

示例：传递默认的组件参数

• config=db&log
  • 启用配置组件
  • 向配置组件传递一个默认参数db
  • 启用日志组件
• config=db,server&log
  • 启用配置组件
  • 向配置组件传递两个默认参数db与log
  • 启用日志组件

示例：传递具名的组件参数

• config&config.dir=folder1
  • 启用配置组件
  • 向配置组件传递一个dir参数folder1
• config.dir=folder1
  • 向配置组件传递一个dir参数folder1（单独设置不会启动组件）

示例：组件别名

• config&config:sms
  • 启用配置组件
  • 启用名为sms的配置组件

示例：组件空间

• config:aaa&config:sms:vvv
  • 在aaa环境下，启用配置组件
  • 在vvv环境下，启用sms配置组件

示例：综合应用

• dir=folder1&config&dir:sms:vvv=folder2&config:sms:vvv
  • 设置默认环境的工作目录为folder1
  • 在默认环境，启用配置组件，它将使用folder1作为工作目录
  • 设置vvv环境的工作目录为folder2
  • 在vvv环境下，启用sms配置组件，它将使用folder2作为工作目录

传递初始化配置

盘古支持通过多种方式传递初始化配置：

• cli：来自命令行参数（CLI）（暂未实现）
• spc：specifier，来自import语法的说明符
• env：来自环境变量NENV_PANGU

优先级

通常情况下，组件们的使用配置的优先级是相同的。不同传递方式的优先级从高到低排列如下：

cli > spc > env

定位

在我使用习惯，不同传递方式有着这不同的使用定位，推荐如下：

• spc：优先使用的主力。与import语法的定位相类似，每一个js文件都应该明确需要什么组件
• cli：适用于单次运行的特殊配置
  • 例如，单独调试运行时，将日志路径修改到另一个位置
  • 例如，类似ffmpeg、magick等工具型程序，每次调用需要传递不同参数
• env：适用于多个入口或程序之间的共有配置
  • 例如，在英文系统中统一将日志语言设置为中文
  • 例如，入口模块与子模块使用相同的配置

导入语法的内联参数

Node.js导入ES模块时，会将导入说明符解析并转换为URL。因此可以在导入说明符中，按照URL标准加入query参数
盘古利用此机制，传递初始化配置说明符

// 注意：由于Node.js实现细节的限制，说明符中必须包含`/index.js`，否则会因为无法识别而导入失败
// ✖ 无法导入
import '@nuogz/pangu?i18n';
// ✔ 正确导入
import '@nuogz/pangu/index.js?i18n&dir';


// i18n组件会设置NENV_I18N_FORMAT变量（默认值：hades），供后续导入的@nuogz/i18n使用
console.log(process.env.NENV_I18N_FORMAT); // hades

环境变量NENV_PANGU

盘古可以根据环境变量中的NENV_PANGU变量，来决定加载什么组件。
NENV_PANGU值的格式是初始化配置说明符

以windows的批处理（cmd）为例：

set NENV_PANGU=i18n&dir

node index.js

index.js

import '@nuogz/pangu';

// 运行程序前（或在系统中）设置NENV_PANGU变量，启用了i18n组件
console.log(process.env.NENV_I18N_FORMAT); // hades

盘古是通过Node.js提供的process.env来获取环境变量的。而process.env是允许重新赋值的，因此以下形式是可行的：

• 如果是项目中有多个程序入口的情况，且有统一的初始化配置，推荐按该形式构建

index.env.js

process.env.NENV_PANGU = 'i18n&dir';

index.js

• 请确保index.env.js在@nuogz/pangu之前被导入。import语法是按顺序加载的

import './index.env.js';
import { C, G } from '@nuogz/pangu';

命令行（WIP）

在v4.x版本中是支持通过命令行对部分组件传递初始化配置的
但在v5.x版本由于需求下降、未梳理如何设计有扩展性的参数、未测试如何配合Commander.js特性等多个原因
因此决定在v5.x早期版本中，暂不提供来自命令行的参数指定

组件

环境变量

NENV_PANGU

初始化配置，格式与URL query部分相同

NENV_PANGU_DIR

部分组件需要的的工作目录，详情见dir组件

前置组件

国际化i18n

对国际化库@nuogz/i18n的两个初始化环境变量NENV_I18N进行设置
初始化配置将直接变更进程的NENV_I18N环境变量

NENV_I18N=locale赋值优先级

• 具名参数locale的参数
  • 支持多个参数
  • 特殊插入值
    • <sys>：系统当前语言，等于Intl.DateTimeFormat().resolvedOptions().locale
• 默认非具名参数1
• Intl.DateTimeFormat().resolvedOptions().locale

NENV_I18N=format赋值优先级

• 具名参数format的参数1
• 默认非具名参数2
• "hades"

导出变量

• i18n Object{ locaLe, format }
• i18ns 多组件Object

工作目录dir

dir组件将设置并导出一个工作目录(dirWorking)
部分组件将使用该工作目录路径作为其相对根路径
通常情况下，该路径指向的目录需要符合@nuogz/gaia的文件目录结构规范
支持相对路径变换，如<cwd>/../map等价于当前环境工作目录同级的map文件夹

赋值优先级

• 默认非具名参数1
  • 默认值：(空)
• 环境变量NENV_PANGU_DIR
• 当前环境工作目录process.cwd()

特殊插入值

• <entry>
  • 程序入口文件所在的目录，等于path.parse(process.argv[1]).dir
  • 即这通常适用于需要在不同目录下运行的工具型程序
• <cwd>
  • 当前环境工作目录，等于process.cwd()

导出变量

• dirWorking 工作目录路径
• dirsWorking 多组件Object

项目信息package

返回工作目录下的package.json

赋值优先级

• 具名参数dir的参数1
• 默认非具名参数1
• 来自dir组件的dirWorking

导出变量

• package package.json的内容。如无则返回{}
• packages 多组件Object

主要组件

命令行command（WIP）

命令行组件。加载Commander.js处理来自命令行的初始化配置，和程序本身的命令行参数

导出变量

• O 命令行解析结果
• commands 多组件Object

配置config

加载@nuogz/poseidon，默认指定工作目录/config目录作为目标目录

导出变量

• C 命令行解析结果
• configs 多组件Object

日志log

加载@nuogz/hades，默认指定工作目录/log目录作为目标目录

导出变量

• G Hades日志实例
• GG Hades日志实例（如果无，会降级至globalThis.console）
• logs 多组件Object

对其他库或功能的初始化

进程process

• 设定进程的标题
• 对未处理进行日志记录

导出变量

• process 进程实例

时间日期day

对day.js进行符合使用习惯的初始化

导出变量

• Day day.js原始对象

导出相关库

以下直接导出相关库，方便使用

Hades ==> @nuogz/hades

• 导出Hades
• 导出Melinoe
• 导出Zagreus

Poseidon ==> @nuogz/poseidon

Commander ==> commander