@aapzu/tsdotenv 中文文档教程
tsdotenv
Tsdotenv 是一个包,它从 .env
文件(或 process.env
变量)生成经过验证的强类型配置对象。
Installation
# using npm
npm install @aapzu/tsdotenv
# using yarn
yarn add @aapzu/tsdotenv
Usage
在项目的根目录中创建一个 .env 文件。 以 NAME=VALUE 的形式在新行中添加特定于环境的变量。 例如:
DB_HOST=localhost
DB_PORT=5432
DEBUG=true
创建一个配置文件作为环境变量的单一真实位置
import { parse } from '@aapzu/tsdotenv'
const SCHEMA = {
DB_HOST: String,
DB_PORT: { type: Number, default: 3000 },
DEBUG: { type: Boolean, optional: true },
CUSTOM_ENV: { type: ['test', 'prod'] },
// enums and optionals only get typed properly if the
// schema is a readonly object
} as const
const config = parse(SCHEMA, {
path: 'path_to_dotenv_file',
})
/*
typeof config = {
DB_HOST: string,
DB_PORT: number,
DEBUG: boolean | undefined
CUSTOM_ENV: 'test' | 'prod'
}
*/
export default config
在其他文件中使用该配置文件
import config from '../path/to/config'
console.log(DB_HOST, typeof DB_HOST)
// localhost string
console.log(DB_PORT, typeof DB_PORT)
// 5432 number
console.log(DEBUG, typeof DEBUG)
// true boolean
Schema
Schema 是库的核心。 值的解析和验证是根据模式完成的。 可能的模式值类型是:
name | syntax |
---|---|
string | String |
number | Number |
boolean | Boolean |
enum | ['value1', 'value2'] |
string array | Array(String) |
number array | Array(Number) |
boolean array | Array(Boolean) |
模式项具有类型,可能还有默认值。 如果该项目具有没有默认值的 optional: true
,则该值可能最终未定义。
示例架构如下:
const schema = {
BOOLEAN_ARRAY: Array(Boolean),
BOOLEAN: {
type: Boolean,
optional: true,
},
ENUM: {
type: ['foo', 'bar'],
default: 'foo',
},
NUMBER_ARRAY: Array(Number),
NUMBER: {
type: Number,
default: 42,
},
STRING: String,
STRING_ARRAY: Array(String),
}
Options
path
默认值:path.resolve(process.cwd(), '.env')
如果包含环境变量的文件位于其他位置,您可以指定自定义路径。
parse(schema, { path: '/custom/path/to/.env' })
camelCaseKeys
默认值:false
将配置对象的键映射到驼峰命名法中。 示例:
import { parse } from '@aapzu/tsdotenv'
const config = parse({
DB_HOST: String,
DB_PORT: { type: Number, default: 3000 },
}, {
path: 'path_to_dotenv_file',
camelCaseKeys: true
})
/*
typeof config = {
dbHost: string,
dbPort: number,
}
*/
export default config
encoding
默认值:utf8
您可以指定包含环境变量的文件的编码。
parse(schema, { encoding: 'latin1' })
debug
默认值:false
您可以打开日志记录以帮助调试某些键或值未按预期设置的原因。
parse(schema, { debug: process.env.DEBUG })
tsdotenv
Tsdotenv is a package which generates a validated and strongly typed config object from .env
file (or process.env
variables).
Installation
# using npm
npm install @aapzu/tsdotenv
# using yarn
yarn add @aapzu/tsdotenv
Usage
Create a .env file in the root directory of your project. Add environment-specific variables on new lines in the form of NAME=VALUE. For example:
DB_HOST=localhost
DB_PORT=5432
DEBUG=true
Create a config file as a single place of truth for the environment variables
import { parse } from '@aapzu/tsdotenv'
const SCHEMA = {
DB_HOST: String,
DB_PORT: { type: Number, default: 3000 },
DEBUG: { type: Boolean, optional: true },
CUSTOM_ENV: { type: ['test', 'prod'] },
// enums and optionals only get typed properly if the
// schema is a readonly object
} as const
const config = parse(SCHEMA, {
path: 'path_to_dotenv_file',
})
/*
typeof config = {
DB_HOST: string,
DB_PORT: number,
DEBUG: boolean | undefined
CUSTOM_ENV: 'test' | 'prod'
}
*/
export default config
Use that config file in other files
import config from '../path/to/config'
console.log(DB_HOST, typeof DB_HOST)
// localhost string
console.log(DB_PORT, typeof DB_PORT)
// 5432 number
console.log(DEBUG, typeof DEBUG)
// true boolean
Schema
Schema is the heart of the library. The parsing and validation of the values is done according to the schema. Possible schema value types are:
name | syntax |
---|---|
string | String |
number | Number |
boolean | Boolean |
enum | ['value1', 'value2'] |
string array | Array(String) |
number array | Array(Number) |
boolean array | Array(Boolean) |
A schema item has type and possibly a default value. If the item has optional: true
without a default value, it's possible that the value ends up being undefined.
An example schema is as follows:
const schema = {
BOOLEAN_ARRAY: Array(Boolean),
BOOLEAN: {
type: Boolean,
optional: true,
},
ENUM: {
type: ['foo', 'bar'],
default: 'foo',
},
NUMBER_ARRAY: Array(Number),
NUMBER: {
type: Number,
default: 42,
},
STRING: String,
STRING_ARRAY: Array(String),
}
Options
path
Default: path.resolve(process.cwd(), '.env')
You may specify a custom path if your file containing environment variables is located elsewhere.
parse(schema, { path: '/custom/path/to/.env' })
camelCaseKeys
Default: false
Maps the keys of the config object into camelCase. Example:
import { parse } from '@aapzu/tsdotenv'
const config = parse({
DB_HOST: String,
DB_PORT: { type: Number, default: 3000 },
}, {
path: 'path_to_dotenv_file',
camelCaseKeys: true
})
/*
typeof config = {
dbHost: string,
dbPort: number,
}
*/
export default config
encoding
Default: utf8
You may specify the encoding of your file containing environment variables.
parse(schema, { encoding: 'latin1' })
debug
Default: false
You may turn on logging to help debug why certain keys or values are not being set as you expect.
parse(schema, { debug: process.env.DEBUG })