@arki/env 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/env",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Type-safe environment variable parsing for ARKI — defineEnv() built on @t3-oss/env-core with Zod contracts for common variable shapes.",
   "license": "MIT",
   "repository": {
@@ -47,6 +47,12 @@
   },
   "files": [
     "dist/**",
+    "src/**",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/tests/**",
+    "!src/**/test/**",
+    "!src/**/__tests__/**",
     "README.md",
     "LICENSE",
     "package.json"
@@ -56,7 +62,7 @@
     "zod": "4.3.5"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.1.1"
+    "@arki/dot": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/contracts/common.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+
+export const commonContracts = {
+  string: (defaultValue?: string) => {
+    const schema = z.string();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  number: (defaultValue?: number) => {
+    const schema = z.coerce.number();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  port: (defaultValue = 3000) =>
+    z
+      .coerce.number()
+      .min(1, 'Port must be at least 1')
+      .max(65_535, 'Port must be at most 65535')
+      .default(defaultValue),
+
+  nodeEnv: () => z.enum(['development', 'production', 'test']).default('development'),
+
+  boolean: (defaultValue = false) =>
+    z
+      .enum(['true', 'false', '1', '0'])
+      .default(defaultValue ? 'true' : 'false')
+      .transform(val => val === 'true' || val === '1'),
+
+  logLevel: (defaultValue: 'debug' | 'info' | 'warn' | 'error' = 'info') =>
+    z.enum(['debug', 'info', 'warn', 'error']).default(defaultValue),
+};

package/src/contracts/index.ts

@@ -0,0 +1,17 @@
+import { commonContracts } from './common.js';
+import { parseContracts } from './parsing.js';
+import { urlContracts } from './urls.js';
+
+// Unified contracts export
+export const contracts = {
+  ...commonContracts,
+  ...urlContracts,
+  ...parseContracts,
+};
+
+// Individual category exports
+
+
+export {commonContracts} from './common.js';
+export {urlContracts} from './urls.js';
+export {parseContracts} from './parsing.js';

package/src/contracts/parsing.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const parseContracts = {
+  json: <T extends z.ZodType>(schema: T) =>
+    z.string().transform((str) => {
+      const parsed = JSON.parse(str);
+      return schema.parse(parsed) as z.infer<T>;
+    }),
+
+  csvArray: <T extends z.ZodType>(itemSchema: T) =>
+    z.preprocess(
+      (val) => {
+        if (typeof val !== 'string') return val;
+        return val.split(',').map((s) => s.trim());
+      },
+      z.array(itemSchema)
+    ),
+
+  csvSet: <T extends z.ZodType>(itemSchema: T) =>
+    z.preprocess(
+      (val) => {
+        if (typeof val !== 'string') return val;
+        return [...new Set(val.split(',').map((s) => s.trim()))];
+      },
+      z.array(itemSchema)
+    ),
+};

package/src/contracts/urls.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+export const urlContracts = {
+  url: (defaultValue?: string) => {
+    const schema = z.url();
+    return defaultValue ? schema.default(defaultValue) : schema;
+  },
+
+  databaseUrl: () =>
+    z
+      .url()
+      .refine(
+        url => url.startsWith('postgres://') || url.startsWith('postgresql://'),
+        'Database URL must start with postgres:// or postgresql://',
+      ),
+
+  redisUrl: () =>
+    z
+      .url()
+      .refine(
+        url => url.startsWith('redis://') || url.startsWith('rediss://'),
+        'Redis URL must start with redis:// or rediss://',
+      ),
+};

package/src/core/define-env.ts

@@ -0,0 +1,134 @@
+import { createEnv } from '@t3-oss/env-core';
+import type { CreateEnv, DefaultCombinedSchema } from '@t3-oss/env-core';
+import type { ZodType } from 'zod';
+
+/** The issue shape t3-oss hands to `onValidationError`, derived so it stays in sync with the lib. */
+type ValidationIssues = Parameters<
+  NonNullable<Parameters<typeof createEnv>[0]['onValidationError']>
+>[0];
+
+/**
+ * Fold validation issues into a human-legible, log-pipeline-safe string. The t3-oss default handler
+ * logs `issues` as a raw object, which platforms like Coolify collapse to `[Object]` — so the var
+ * that actually failed never reaches the logs. A flat `  path: message` list survives transport.
+ */
+function formatIssues(name: string | undefined, issues: ValidationIssues): string {
+  const label = name ? `[${name}] ` : '';
+  const lines = issues.map(issue => {
+    const path = (issue.path ?? [])
+      .map(seg => (typeof seg === 'object' && seg !== null && 'key' in seg ? String(seg.key) : String(seg)))
+      .join('.');
+    return `  ${path || '(root)'}: ${issue.message}`;
+  });
+  return `❌ ${label}Invalid environment variables:\n${lines.join('\n')}`;
+}
+
+/**
+ * Thin, type-preserving wrapper over `@t3-oss/env-core`'s `createEnv`. Generic over the server,
+ * client, shared and composed schemas so the parsed env keeps its exact inferred types — the wrapper
+ * adds the ARKI defaults (auto `runtimeEnv`, prod-safe `skipValidation`, a legible labelled error
+ * handler) without widening any value to `unknown`.
+ *
+ * `TPrefix` is kept as a string-literal generic on purpose: `createEnv` uses it to enforce that
+ * client keys (and only client keys) carry the prefix. Widening it to `string` would make every
+ * server key collapse to a type-level `ErrorMessage`, so the prefix must stay a literal.
+ */
+export function defineEnv<
+  TServer extends Record<string, ZodType>,
+  TClient extends Record<string, ZodType> = NonNullable<unknown>,
+  TShared extends Record<string, ZodType> = NonNullable<unknown>,
+  const TPrefix extends string = '',
+  const TExtends extends Array<Record<string, unknown>> = [],
+>(config: {
+  /**
+   * Label shown in validation-error logs, e.g. `'@acme/backend'`. Without it a misconfigured
+   * deploy logs a bare "Invalid environment variables" with no hint which env failed — exactly the
+   * blind failure this wrapper exists to prevent.
+   */
+  name?: string;
+  server: TServer;
+  /** Client-side schema. Every key must start with `clientPrefix` (enforced by `createEnv`). */
+  client?: TClient;
+  /** Prefix client keys must carry, e.g. `'VITE_'`. Defaults to `''` (no client vars). */
+  clientPrefix?: TPrefix;
+  /** Shared vars available to both client and server, unprefixed (e.g. `NODE_ENV`). */
+  shared?: TShared;
+  /**
+   * Already-built envs to compose in (e.g. `@arki/auth`, `@arki/db`). Their parsed variables merge
+   * into the result with full types; each was validated by its own `createEnv` at import time.
+   */
+  extends?: TExtends;
+  /**
+   * Explicit runtime source. Omit it and `defineEnv` auto-builds one by reading `process.env` for
+   * every declared key — correct for any server-side env. Provide it only when the auto-build would
+   * be wrong: Vite/`start` apps whose client vars come from `import.meta.env` in the browser, or
+   * keys with a fallback/alias (e.g. `DB_URL: process.env.DB_URL ?? process.env.DATABASE_URL`).
+   */
+  runtimeEnv?: Record<string, string | boolean | number | undefined>;
+  options?: {
+    skipValidation?: boolean;
+    /**
+     * Treat empty-string env values as `undefined` so defaults apply (e.g. `PORT=` in `.env`, or a
+     * Docker arg baked as `X=""`). Defaults to `true` — set `false` only if an app intentionally
+     * accepts `""` as a valid required string.
+     */
+    emptyStringAsUndefined?: boolean;
+    onValidationError?: (issues: ValidationIssues) => never;
+  };
+}): CreateEnv<DefaultCombinedSchema<TServer, TClient, TShared>, TExtends> {
+  const skipValidation =
+    config.options?.skipValidation ?? (!!process.env.CI || process.env.NODE_ENV !== 'development');
+
+  // Use the caller's explicit runtimeEnv when supplied (Vite client vars via import.meta.env, or
+  // fallback aliases). Otherwise auto-build from every declared key (server + client + shared);
+  // createEnv tolerates keys absent from process.env (they parse as undefined → optional/default).
+  let runtimeEnv: Record<string, string | boolean | number | undefined>;
+  if (config.runtimeEnv) {
+    runtimeEnv = config.runtimeEnv;
+  } else {
+    runtimeEnv = {};
+    for (const key of Object.keys(config.server)) {
+      runtimeEnv[key] = process.env[key];
+    }
+    for (const key of Object.keys(config.client ?? {})) {
+      runtimeEnv[key] = process.env[key];
+    }
+    for (const key of Object.keys(config.shared ?? {})) {
+      runtimeEnv[key] = process.env[key];
+    }
+  }
+
+  const onValidationError =
+    config.options?.onValidationError ??
+    ((issues: ValidationIssues): never => {
+      const message = formatIssues(config.name, issues);
+      console.error(message);
+      throw new Error(message);
+    });
+
+  // `createEnv`'s `server`/`client` params are conditional on `clientPrefix` being a *concrete*
+  // string literal; inside a generic wrapper `TPrefix` is abstract, so the body cannot be verified
+  // for all prefixes and the call argument must be asserted once. The PUBLIC contract stays exact:
+  // the explicit return type above reconstructs `createEnv`'s own result from the generics, and the
+  // caller's `server`/`client`/`extends` are fully type-checked against `TServer`/`TClient`/`TExtends`
+  // at the call site. This is the only seam where types are asserted — value types are never widened.
+  const options = {
+    shared: config.shared ?? {},
+    extends: config.extends,
+    server: config.server,
+    client: config.client ?? {},
+    clientPrefix: config.clientPrefix ?? '',
+    runtimeEnv,
+    skipValidation,
+    // Default ON: in containerized deploys an unset var is baked as "" (e.g. Docker `ENV X=${X}`
+    // with no build arg), not left absent. Treating "" as undefined lets `.default()`/`.optional()`
+    // apply as intended instead of failing format checks like `z.url()` on an empty string.
+    emptyStringAsUndefined: config.options?.emptyStringAsUndefined ?? true,
+    onValidationError,
+  } satisfies Record<string, unknown>;
+
+  return createEnv(options as Parameters<typeof createEnv>[0]) as CreateEnv<
+    DefaultCombinedSchema<TServer, TClient, TShared>,
+    TExtends
+  >;
+}

package/src/core/index.ts

@@ -0,0 +1,2 @@
+export { defineEnv } from './define-env.js';
+export { contracts } from '../contracts/index.js';

package/src/dot.ts

@@ -0,0 +1,95 @@
+/**
+ * DOT adapter for `@arki/env`.
+ *
+ * Wraps `defineEnv()` as a DOT pip so a DOT app can validate its
+ * environment alongside any other services. The pip is sync (env
+ * validation is sync), so the `boot` hook returns the validated env
+ * object synchronously through the standard provides channel.
+ *
+ * @example
+ * ```ts
+ * import { defineApp } from '@arki/dot';
+ * import { env } from '@arki/env/dot';
+ * import { z } from 'zod';
+ *
+ * const app = await defineApp('my-app')
+ *   .use(env({ schema: { PORT: z.coerce.number().default(3000) } }))
+ *   .boot();
+ *
+ * console.log(app.services.env.PORT); // number, typed.
+ * ```
+ *
+ * To mount a second env scope in the same app, rename the published wire
+ * key at the mount site:
+ *
+ * ```ts
+ * import { rename } from '@arki/dot';
+ *
+ * .use(env({ schema: appSchema }))
+ * .use(rename(env({ schema: publicSchema }), { env: 'publicEnv' }, 'public-env'))
+ * ```
+ *
+ * The `@arki/dot` package is an OPTIONAL peer of `@arki/env`. Importing
+ * this adapter without `@arki/dot` installed will fail at module load —
+ * that is intentional: the adapter only makes sense in a DOT app.
+ */
+
+import { pip, type EmptyShape, type Pip } from '@arki/dot/pip';
+import type { ZodType } from 'zod';
+
+import { defineEnv } from './core/define-env.js';
+
+/**
+ * Options for the env DOT adapter.
+ *
+ * @typeParam TSchema - The shape of the `server` schema record. The
+ *   resulting `app.services.env` is typed from this.
+ */
+export type EnvDotOptions<TSchema extends Record<string, ZodType>> = {
+  /** Zod schemas for each env var the pip validates. */
+  readonly schema: TSchema;
+  /**
+   * Forwarded to `defineEnv`. If `true`, the validator is skipped
+   * entirely. By default, validation is skipped when `CI` is set or
+   * `NODE_ENV !== 'development'`.
+   */
+  readonly skipValidation?: boolean;
+};
+
+/** The shape of services published by the env adapter. */
+export type EnvServices<TSchema extends Record<string, ZodType>> = {
+  readonly env: { readonly [K in keyof TSchema]: TSchema[K] extends ZodType<infer U> ? U : never };
+};
+
+/**
+ * Build a DOT pip that validates and publishes a typed `env` service.
+ *
+ * @param options - Schema + optional config.
+ * @returns A pip that publishes `services.env`.
+ */
+export function env<TSchema extends Record<string, ZodType>>(
+  options: EnvDotOptions<TSchema>,
+): Pip<EmptyShape, EnvServices<TSchema>> {
+  return pip({
+    name: 'env',
+    version: '0.1.0',
+    configure(ctx) {
+      ctx.registerService('env', 'env');
+    },
+    boot() {
+      const validated = defineEnv({
+        server: options.schema,
+        options:
+          options.skipValidation !== undefined
+            ? { skipValidation: options.skipValidation }
+            : undefined,
+      });
+      // `defineEnv` returns a Proxy from `@t3-oss/env-core`; we narrow it
+      // to the schema-derived shape so downstream typing flows through.
+      // The runtime guarantee comes from Zod-side validation inside
+      // `defineEnv`. No `any` involved — the cast is type-only.
+      const envObject = validated as unknown as EnvServices<TSchema>['env'];
+      return { env: envObject };
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// Re-export contracts for convenience
+export { contracts } from './contracts/index.js';