@ucdjs/env 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @ucdjs/env
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![codecov][codecov-src]][codecov-href]
+
+Environment configuration for UCDJS projects.
+
+## Installation
+
+```bash
+npm install @ucdjs/env
+```
+
+## 📄 License
+
+Published under [MIT License](./LICENSE).
+
+[npm-version-src]: https://img.shields.io/npm/v/@ucdjs/env?style=flat&colorA=18181B&colorB=4169E1
+[npm-version-href]: https://npmjs.com/package/@ucdjs/env
+[npm-downloads-src]: https://img.shields.io/npm/dm/@ucdjs/env?style=flat&colorA=18181B&colorB=4169E1
+[npm-downloads-href]: https://npmjs.com/package/@ucdjs/env
+[codecov-src]: https://img.shields.io/codecov/c/gh/ucdjs/ucd?style=flat&colorA=18181B&colorB=4169E1
+[codecov-href]: https://codecov.io/gh/ucdjs/ucd

package/dist/index.d.mts

@@ -0,0 +1,61 @@
+//#region src/constants.d.ts
+/**
+ * HTTP header name for specifying the type of UCD statistics.
+ *
+ * This constant defines the header key used to indicate the type of
+ * statistics being transmitted or requested in UCD-related HTTP communications.
+ *
+ * @example
+ * ```typescript
+ * import { UCD_STAT_TYPE_HEADER, UCD_STAT_SIZE_HEADER } from "@ucdjs/env";
+ *
+ * headers[UCD_STAT_TYPE_HEADER] = "file";
+ * headers[UCD_STAT_SIZE_HEADER] = "1024";
+ * ```
+ */
+declare const UCD_STAT_TYPE_HEADER = "X-UCD-Stat-Type";
+declare const UCD_STAT_SIZE_HEADER = "X-UCD-Stat-Size";
+declare const UCD_STAT_CHILDREN_HEADER = "X-UCD-Stat-Children";
+declare const UCD_STAT_CHILDREN_FILES_HEADER = "X-UCD-Stat-Children-Files";
+declare const UCD_STAT_CHILDREN_DIRS_HEADER = "X-UCD-Stat-Children-Dirs";
+//#endregion
+//#region src/env-constants.d.ts
+/**
+ * Base URL for the UCDJS API
+ * @default "https://api.ucdjs.dev"
+ */
+declare const UCDJS_API_BASE_URL: string;
+/**
+ * Base URL for the UCDJS Store API
+ * @default "https://ucd-store.ucdjs.dev"
+ */
+declare const UCDJS_STORE_BASE_URL: string;
+declare const DEFAULT_USER_AGENT = "ucdjs.dev (https://ucdjs.dev)";
+//#endregion
+//#region src/required-env.d.ts
+/**
+ * Validates that required environment variables are present and returns a typed environment object.
+ *
+ * This function ensures that specified environment variables exist in the provided environment object.
+ * If any required keys are missing, it throws an error. Otherwise, it returns the environment object
+ * with proper typing where required keys are guaranteed to be present.
+ *
+ * @template {object} Env - The type of the environment object
+ * @template {keyof Env} Keys - The keys from Env that are required to be present
+ * @param {Env} env - The environment object to validate
+ * @param {Keys[]} requiredKeys - Array of keys that must be present in the environment object
+ * @returns {Required<Pick<Env, Keys>> & Partial<Omit<Env, Keys>>} The environment object with required keys typed as non-nullable and optional keys as partial
+ * @throws {Error} When any of the required environment variables are missing
+ *
+ * @example
+ * ```typescript
+ * import { requiredEnv } from "@ucdjs/env";
+ * const env = { DATABASE_URL: "...", API_KEY: "...", OPTIONAL_VAR: undefined };
+ * const validatedEnv = requiredEnv(env, ["DATABASE_URL", "API_KEY"]);
+ * // validatedEnv.DATABASE_URL and validatedEnv.API_KEY are guaranteed to be present
+ * // validatedEnv.OPTIONAL_VAR remains optional
+ * ```
+ */
+declare function requiredEnv<Env extends object, Keys extends keyof Env>(env: Env, requiredKeys: Keys[]): Required<Pick<Env, Keys>> & Partial<Omit<Env, Keys>>;
+//#endregion
+export { DEFAULT_USER_AGENT, UCDJS_API_BASE_URL, UCDJS_STORE_BASE_URL, UCD_STAT_CHILDREN_DIRS_HEADER, UCD_STAT_CHILDREN_FILES_HEADER, UCD_STAT_CHILDREN_HEADER, UCD_STAT_SIZE_HEADER, UCD_STAT_TYPE_HEADER, requiredEnv };

package/dist/index.mjs

@@ -0,0 +1,70 @@
+import { getOwnProperty } from "@luxass/utils";
+
+//#region src/constants.ts
+/**
+* HTTP header name for specifying the type of UCD statistics.
+*
+* This constant defines the header key used to indicate the type of
+* statistics being transmitted or requested in UCD-related HTTP communications.
+*
+* @example
+* ```typescript
+* import { UCD_STAT_TYPE_HEADER, UCD_STAT_SIZE_HEADER } from "@ucdjs/env";
+*
+* headers[UCD_STAT_TYPE_HEADER] = "file";
+* headers[UCD_STAT_SIZE_HEADER] = "1024";
+* ```
+*/
+const UCD_STAT_TYPE_HEADER = "X-UCD-Stat-Type";
+const UCD_STAT_SIZE_HEADER = "X-UCD-Stat-Size";
+const UCD_STAT_CHILDREN_HEADER = "X-UCD-Stat-Children";
+const UCD_STAT_CHILDREN_FILES_HEADER = "X-UCD-Stat-Children-Files";
+const UCD_STAT_CHILDREN_DIRS_HEADER = "X-UCD-Stat-Children-Dirs";
+
+//#endregion
+//#region src/env-constants.ts
+const env = typeof process === "undefined" ? {} : process.env;
+/**
+* Base URL for the UCDJS API
+* @default "https://api.ucdjs.dev"
+*/
+const UCDJS_API_BASE_URL = env.UCDJS_API_BASE_URL || "https://api.ucdjs.dev";
+/**
+* Base URL for the UCDJS Store API
+* @default "https://ucd-store.ucdjs.dev"
+*/
+const UCDJS_STORE_BASE_URL = env.UCDJS_STORE_BASE_URL || "https://ucd-store.ucdjs.dev";
+const DEFAULT_USER_AGENT = "ucdjs.dev (https://ucdjs.dev)";
+
+//#endregion
+//#region src/required-env.ts
+/**
+* Validates that required environment variables are present and returns a typed environment object.
+*
+* This function ensures that specified environment variables exist in the provided environment object.
+* If any required keys are missing, it throws an error. Otherwise, it returns the environment object
+* with proper typing where required keys are guaranteed to be present.
+*
+* @template {object} Env - The type of the environment object
+* @template {keyof Env} Keys - The keys from Env that are required to be present
+* @param {Env} env - The environment object to validate
+* @param {Keys[]} requiredKeys - Array of keys that must be present in the environment object
+* @returns {Required<Pick<Env, Keys>> & Partial<Omit<Env, Keys>>} The environment object with required keys typed as non-nullable and optional keys as partial
+* @throws {Error} When any of the required environment variables are missing
+*
+* @example
+* ```typescript
+* import { requiredEnv } from "@ucdjs/env";
+* const env = { DATABASE_URL: "...", API_KEY: "...", OPTIONAL_VAR: undefined };
+* const validatedEnv = requiredEnv(env, ["DATABASE_URL", "API_KEY"]);
+* // validatedEnv.DATABASE_URL and validatedEnv.API_KEY are guaranteed to be present
+* // validatedEnv.OPTIONAL_VAR remains optional
+* ```
+*/
+function requiredEnv(env, requiredKeys) {
+	for (const key of requiredKeys) if (getOwnProperty(env, key) == null) throw new Error(`Missing required env var: ${key}`);
+	return env;
+}
+
+//#endregion
+export { DEFAULT_USER_AGENT, UCDJS_API_BASE_URL, UCDJS_STORE_BASE_URL, UCD_STAT_CHILDREN_DIRS_HEADER, UCD_STAT_CHILDREN_FILES_HEADER, UCD_STAT_CHILDREN_HEADER, UCD_STAT_SIZE_HEADER, UCD_STAT_TYPE_HEADER, requiredEnv };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ucdjs/env",
+  "version": "0.1.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/env"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@luxass/utils": "2.7.3"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "eslint": "10.0.0",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3",
+    "@ucdjs-tooling/tsconfig": "1.0.0",
+    "@ucdjs-tooling/tsdown-config": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json"
+  }
+}