Make ArkType optional and support Standard Schema directly #704
Conversation
…alize utility functions.
- Normalize ArkEnvError constructor input - Add public issues property to ArkEnvError - Deprecate and refactor formatErrors function
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughArkType is now optional and loaded at runtime; createEnv detects Standard Schema vs ArkType validators, dispatches validation accordingly, normalizes errors to EnvIssue[], preserves ArkType-only coercion, adjusts types (InferType/EnvSchemaWithType), and updates plugin callsites and tests for mixed-validator support. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant createEnv
participant detectValidatorType
participant validateStandard
participant validateArkType
participant formatErrors
User->>createEnv: createEnv(def, config)
createEnv->>detectValidatorType: detectValidatorType(def)
alt Standard Schema
detectValidatorType-->>validateStandard: def (StandardSchemaV1)
validateStandard->>validateStandard: run validator -> value or issues
validateStandard->>formatErrors: map issues -> EnvIssue[]
else ArkType
detectValidatorType-->>validateArkType: def (ArkType)
validateArkType->>validateArkType: load arktype, apply coercion, validate
validateArkType->>formatErrors: map ArkErrors -> EnvIssue[]
end
alt No errors
formatErrors-->>createEnv: success
createEnv-->>User: return inferred value
else Errors
formatErrors-->>createEnv: formatted issues
createEnv-->>User: throw ArkEnvError with issues
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
bot
added
arkenv
commit: |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
… API consistency.
github-actions
bot
added
the
@arkenv/vite-plugin
…nt, with `defineEnv` now an alias for compatibility.
- Replaced defineEnv with arkenv calls - Removed obsolete wrapped schema test - Updated test descriptions for arkenv
… line in arkenv test.
|
yamcodes
changed the title
- `arkenv()` now strictly expects a schema mapping object - No longer accepts top-level compiled ArkType or Zod
github-actions
bot
added
docs
- Allow compiled ArkType schemas as top-level arg - Support standard Zod schemas as top-level arg - Remove invalid schema argument error - Update Bun and Vite plugins to support new schema types
- Remove deprecated formatErrors function. - Update tests to use formatIssues directly. - Simplify error formatting logic.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @packages/arkenv/src/create-env.ts:
- Around line 42-66: In detectValidatorType simplify the ArkType brand detection
by stopping the assumption that infer is a function; replace the typeof d.infer
=== "function" check with a property-existence check (e.g., "'infer' in d") and
keep the existing fallback for d.t (e.g., "typeof d.t === 'object' && d.t !==
null && 'infer' in d.t") so hasArktypeBrand consistently uses property presence;
update the hasArktypeBrand definition to use these existence checks.
🧹 Nitpick comments (2)
packages/vite-plugin/src/index.test.ts.tmp (1)
30-31: Consider a more conventional mock retrieval pattern.The current pattern places
awaitinsidevi.mocked(), which works but is less conventional. Consider awaiting the import first for clarity:♻️ Suggested refactor
-// Get the mocked functions -const { createEnv: mockCreateEnv } = vi.mocked(await import("arkenv")); +// Get the mocked functions +const arkenvMock = await import("arkenv"); +const { createEnv: mockCreateEnv } = vi.mocked(arkenvMock);This makes the execution order more explicit and follows common patterns in Vitest documentation.
packages/internal/scope/src/index.ts (1)
16-18: Consider moving type imports to the top of the file.While valid, placing
import typestatements mid-file (after the JSDoc block) is unconventional. Moving them to the top improves readability and aligns with typical TypeScript conventions.Suggested organization
import { createRequire } from "node:module"; import { host, port } from "@repo/keywords"; import type { scope as ArkScope, type as ArkType } from "arktype"; +import type { ArkEnvScope } from "./scope-def"; + +export type { ArkEnvScope } from "./scope-def"; const require = createRequire(import.meta.url); let _$: any; /** * The root scope for the ArkEnv library, ... */ -import type { ArkEnvScope } from "./scope-def"; - -export type { ArkEnvScope } from "./scope-def"; - export const $: ArkEnvScope = new Proxy(
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (12)
packages/arkenv/src/create-env.tspackages/arkenv/src/type.tspackages/arkenv/src/utils/coerce.tspackages/internal/scope/package.jsonpackages/internal/scope/src/index.tspackages/internal/scope/src/scope-def.tspackages/internal/scope/tsconfig.jsonpackages/internal/types/src/infer-type.tspackages/vite-plugin/package.jsonpackages/vite-plugin/src/__fixtures__/standard-schema/config.tspackages/vite-plugin/src/index.test.tspackages/vite-plugin/src/index.test.ts.tmp
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/vite-plugin/src/index.test.ts
🧰 Additional context used
📓 Path-based instructions (6)
packages/*/package.json
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Packages in packages/ directory must be published to npm and require changesets for versioning, proper exports, and type definitions
Files:
packages/vite-plugin/package.json
**/package.json
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use workspace:* protocol for workspace dependencies between packages
Files:
packages/vite-plugin/package.jsonpackages/internal/scope/package.json
{packages,apps,tooling}/**/package.json
📄 CodeRabbit inference engine (.cursor/rules/pnpm.mdc)
When referencing workspace packages in dependencies, use the
workspace:*protocol instead of version numbers
Files:
packages/vite-plugin/package.jsonpackages/internal/scope/package.json
packages/arkenv/**/*.ts
📄 CodeRabbit inference engine (.cursor/rules/arktype.mdc)
packages/arkenv/**/*.ts: Use ArkType'stype()function to define schemas in environment variable definitions
Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Use the scoped$type system for custom types defined inscope.ts
Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Use union types for enums in ArkType schemas (e.g.,"'dev' | 'prod'") instead of separate enum definitions
Leverage ArkType's built-in types (e.g.,string.host,number.port) where possible in environment schemas
Convert ArkType validation errors toArkEnvErrorfor user-friendly error messages that include variable name and expected type
Files:
packages/arkenv/src/create-env.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
**/*.{ts,tsx}: Prefertypeoverinterfacefor type definitions in TypeScript
Use TypeScript 5.1+ features when appropriate
Leverageconsttype parameters for better inference in TypeScript
Use JSDoc comments for public APIs
Use tabs for indentation (configured in Biome)
Use double quotes for strings (configured in Biome)
Organize imports automatically (Biome handles this)
Avoid explicit types when TypeScript can infer them (noInferrableTypeserror)
Useas constwhere appropriate for immutable values (useAsConstAssertionerror)
Don't reassign function parameters (noParameterAssignerror)
Place default parameters last in function signatures (useDefaultParameterLasterror)
Always initialize enum values (useEnumInitializerserror)
Declare one variable per statement (useSingleVarDeclaratorerror)
Avoid unnecessary template literals (noUnusedTemplateLiteralerror)
PreferNumber.parseIntover globalparseInt(useNumberNamespaceerror)
Use kebab-case for TypeScript filenames (e.g.,create-env.ts)
Use camelCase for function names (e.g.,createEnv)
Use PascalCase for type names (e.g.,ArkEnvError)
Use UPPER_SNAKE_CASE for environment variables and constants
Include examples in JSDoc comments when helpful for public APIs
Document complex type logic with JSDoc comments
UseArkEnvErrorfor environment variable validation errors
Provide clear, actionable error messages that include the variable name and expected type
**/*.{ts,tsx}: UsecreateEnv(schema)function (or default import asarkenv) to create validated environment objects in TypeScript
Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Use ArkEnvError for environment variable errors instead of generic Error types
For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'deve...
Files:
packages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/vite-plugin/src/__fixtures__/standard-schema/config.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
**/index.ts
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
Use barrel exports (
index.ts) for package entry points
Files:
packages/internal/scope/src/index.ts
🧠 Learnings (41)
📓 Common learnings
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 498
File: apps/playgrounds/node/index.ts:2-2
Timestamp: 2025-12-05T20:33:10.676Z
Learning: ArkType 2.1.28+ supports Standard Schema specification, allowing interoperability with other Standard Schema-compliant validation libraries (e.g., Zod, Valibot) within the same schema definition
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types
📚 Learning: 2025-12-26T19:27:11.710Z
Learnt from: danciudev
Repo: yamcodes/arkenv PR: 614
File: packages/vite-plugin/src/index.test.ts:641-654
Timestamp: 2025-12-26T19:27:11.710Z
Learning: In packages/vite-plugin/src/**/*.test.ts: The test suite uses `env.test` files (without leading dot) as test fixtures that are manually read by the `readTestConfig` helper function and stubbed into process.env with `vi.stubEnv`, not as files to be read by Vite's loadEnv during tests.
Applied to files:
packages/vite-plugin/package.jsonpackages/vite-plugin/src/index.test.ts.tmppackages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-11-24T16:04:11.901Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-11-24T16:04:11.901Z
Learning: Applies to tooling/*/package.json : Tooling in tooling/ directory contains development and testing tools that are not published to npm and excluded from changesets
Applied to files:
packages/vite-plugin/package.jsonpackages/internal/scope/package.json
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to packages/vite-plugin/src/**/*.test.ts : Use fixture-based testing pattern for Vite plugin tests by placing fixtures in __fixtures__ directory
Applied to files:
packages/vite-plugin/package.jsonpackages/vite-plugin/src/index.test.ts.tmppackages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to packages/vite-plugin/src/**/*.test.ts : Test the Vite plugin using the with-vite-react example as a fixture and validate that the plugin works with real Vite projects
Applied to files:
packages/vite-plugin/package.jsonpackages/vite-plugin/src/index.test.ts.tmppackages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-11-24T16:04:11.901Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-11-24T16:04:11.901Z
Learning: Applies to packages/*/package.json : Packages in packages/ directory must be published to npm and require changesets for versioning, proper exports, and type definitions
Applied to files:
packages/vite-plugin/package.jsonpackages/internal/scope/package.json
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Use Vitest for unit and integration tests
Applied to files:
packages/vite-plugin/package.jsonpackages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-11-24T16:04:11.901Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-11-24T16:04:11.901Z
Learning: packages/arkenv should not depend on other workspace packages; packages/vite-plugin depends on arkenv; apps/www may depend on workspace packages
Applied to files:
packages/vite-plugin/package.json
📚 Learning: 2025-11-29T08:00:08.044Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/pnpm.mdc:0-0
Timestamp: 2025-11-29T08:00:08.044Z
Learning: Applies to package.json : Configure only built dependencies (native modules) in `pnpm.onlyBuiltDependencies`, including: biomejs/biome, sentry/cli, swc/core, tailwindcss/oxide, vercel/speed-insights, esbuild, and sharp
Applied to files:
packages/vite-plugin/package.jsonpackages/internal/scope/package.json
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")
Applied to files:
packages/vite-plugin/package.jsonpackages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/arkenv/src/utils/coerce.tspackages/vite-plugin/src/__fixtures__/standard-schema/config.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{test,integration.test}.{ts,tsx} : Mock `process.env` in unit tests to test different environment variable scenarios
Applied to files:
packages/vite-plugin/src/index.test.ts.tmppackages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.test.{ts,tsx} : Create unit tests with `.test.ts` or `.test.tsx` suffix located alongside source files, testing individual functions and components in isolation with mocked dependencies
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Test individual functions, components, and hooks in isolation with mocked dependencies in unit tests
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Mock external dependencies (clipboard, network, etc.) in unit tests
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Test how multiple units (components, hooks, functions) work together without mocking their interactions in integration tests
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Mock at component boundaries (network, time, context)
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{test,integration.test}.{ts,tsx} : Use Vitest's `describe`/`it` structure for all test files
Applied to files:
packages/vite-plugin/src/index.test.ts.tmp
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use the scoped `$` type system for custom types defined in `scope.ts`
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/scope.ts : Define custom types in `scope.ts` using ArkType's scoped type system for reusability across schemas
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Prefer `type` over `interface` for type definitions in TypeScript
Applied to files:
packages/internal/scope/tsconfig.json
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use TypeScript 5.1+ features when appropriate
Applied to files:
packages/internal/scope/tsconfig.json
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Avoid explicit types when TypeScript can infer them (`noInferrableTypes` error)
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/types/src/infer-type.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/vite-plugin/src/__fixtures__/standard-schema/config.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Leverage `const` type parameters for better inference in TypeScript
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/types/src/infer-type.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Applied to files:
packages/internal/scope/tsconfig.jsonpackages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.ts
📚 Learning: 2025-11-29T08:00:08.044Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/pnpm.mdc:0-0
Timestamp: 2025-11-29T08:00:08.044Z
Learning: Applies to package.json : The project uses `pnpm10.20.0` as specified in the `packageManager` field
Applied to files:
packages/internal/scope/package.json
📚 Learning: 2025-11-24T16:04:11.901Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-11-24T16:04:11.901Z
Learning: Applies to **/package.json : Use workspace:* protocol for workspace dependencies between packages
Applied to files:
packages/internal/scope/package.json
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Applied to files:
packages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Applied to files:
packages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Applied to files:
packages/internal/scope/package.jsonpackages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Applied to files:
packages/arkenv/src/create-env.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript
Applied to files:
packages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/arkenv/src/utils/coerce.tspackages/vite-plugin/src/__fixtures__/standard-schema/config.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Applied to files:
packages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/internal/types/src/infer-type.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Applied to files:
packages/arkenv/src/create-env.tspackages/arkenv/src/utils/coerce.tspackages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-12-22T19:44:11.474Z
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 596
File: examples/basic/index.ts:4-5
Timestamp: 2025-12-22T19:44:11.474Z
Learning: In examples/basic/index.ts: Use explicit ArkType syntax (e.g., "string.ip | 'localhost'", "0 <= number.integer <= 65535") instead of built-in validators (string.host, number.port) to showcase ArkType's type system capabilities for educational purposes.
Applied to files:
packages/arkenv/src/create-env.tspackages/internal/scope/src/scope-def.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/type.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types
Applied to files:
packages/arkenv/src/create-env.tspackages/arkenv/src/utils/coerce.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Provide clear, actionable error messages that include the variable name and expected type
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use descriptive environment variable names that indicate purpose and format (e.g., DATABASE_URL, NODE_ENV, FEATURE_FLAG)
Applied to files:
packages/vite-plugin/src/__fixtures__/standard-schema/config.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use UPPER_SNAKE_CASE for environment variables and constants
Applied to files:
packages/vite-plugin/src/__fixtures__/standard-schema/config.ts
🧬 Code graph analysis (4)
packages/arkenv/src/create-env.ts (6)
packages/arkenv/src/errors.ts (2)
EnvIssue(7-10)ArkEnvError(54-62)packages/arkenv/src/utils/coerce.ts (1)
coerce(296-344)packages/arkenv/src/type.ts (1)
type(7-14)packages/arkenv/src/index.ts (2)
createEnv(13-13)ArkEnvError(14-14)packages/internal/types/src/schema.ts (2)
SchemaShape(5-5)SchemaShape(6-6)packages/internal/types/src/infer-type.ts (1)
InferType(10-27)
packages/internal/types/src/infer-type.ts (1)
packages/arkenv/src/type.ts (1)
type(7-14)
packages/arkenv/src/type.ts (1)
packages/internal/scope/src/index.ts (2)
$(20-49)$(51-51)
packages/internal/scope/src/index.ts (2)
packages/internal/scope/src/scope-def.ts (1)
ArkEnvScope(19-19)packages/arkenv/src/type.ts (1)
type(7-14)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: test-e2e (e2e)
- GitHub Check: test-e2e (a11y)
- GitHub Check: test-build (lts/*)
- GitHub Check: test-build (latest)
- GitHub Check: test-typesafety
- GitHub Check: Deploy-Preview
🔇 Additional comments (19)
packages/internal/scope/package.json (1)
40-40: LGTM!Adding
@types/nodeas a devDependency is appropriate for TypeScript development in this internal package, especially given the runtime proxy and scope utilities being developed as part of the ArkType optional support work. Thecatalog:version specifier is consistent with other dependencies in this package.packages/vite-plugin/src/index.test.ts.tmp (1)
1-33: Clarify the purpose of this.tmpfile or remove it.This file has a
.tmpextension, which prevents it from being executed by the test runner. Vitest only processes.test.tsor.spec.tsfiles by default. The AI summary indicates that a separate concrete test filepackages/vite-plugin/src/index.test.tswas added, suggesting this.tmpfile may be:
- Leftover scaffolding that should be removed
- Work-in-progress code accidentally committed
- Intentionally excluded template/reference that should be documented
Additionally, all imports and defined variables are unused, and no test cases are present, confirming this is incomplete.
Please clarify whether this file should be:
- Removed (if obsolete)
- Renamed to remove
.tmpextension (if it contains tests to run)- Documented with a comment explaining its purpose (if it's intentional scaffolding)
packages/internal/scope/tsconfig.json (1)
17-17: No action needed—"types": ["node"]is appropriately configured.The
@types/nodedependency is correctly declared indevDependencies(via"catalog:"), and the source code legitimately uses Node.js APIs (createRequireandrequire()) that require these type definitions. No other@types/*packages are used in the codebase.Likely an incorrect or invalid review comment.
packages/vite-plugin/package.json (1)
24-25: LGTM!Adding
zodas a devDependency is appropriate for testing Standard Schema integration in the Vite plugin fixtures. Thecatalog:protocol is consistent with other workspace dependencies.packages/vite-plugin/src/__fixtures__/standard-schema/config.ts (1)
1-5: LGTM!Well-structured test fixture demonstrating Standard Schema (Zod) integration. The
VITE_prefix follows Vite conventions, andUPPER_SNAKE_CASEnaming adheres to coding guidelines.packages/arkenv/src/type.ts (2)
16-16: Type re-export provides useful alias for external consumers.The
atalias allows consumers to reference ArkType's type in type position without runtime import.
3-14: Proxy implementation correctly enables lazy ArkType loading.The proxy pattern with
applyandgettraps properly forwards calls to$.type. ThethisArghandling ensures correct binding whentype()is called directly. Aconstructtrap is not needed—ArkType'stypefunction is only called as a function, never with thenewoperator.packages/internal/scope/src/index.ts (1)
20-49: Lazy-loading proxy correctly implements optional ArkType dependency.The implementation properly:
- Caches the loaded scope in
_$to avoid repeated require calls- Provides a clear error message when ArkType is missing
- Uses
createRequirefor ESM compatibilitypackages/arkenv/src/utils/coerce.ts (2)
296-320: Robust input validation and runtime ArkType loading.The validation checks correctly ensure the schema has required methods before proceeding. The runtime loading pattern is consistent with other files in this PR, and error messages are clear and actionable.
341-343: Pipeline construction correctly handles type casting.The
as unknown as Tcast is necessary due to scope mismatch betweentype("unknown")and the original schema's scope. The comment at lines 335-340 appropriately explains this design decision.packages/internal/types/src/infer-type.ts (2)
1-3: Imports correctly bring in types needed for dual-validator support.The addition of
StandardSchemaV1from@standard-schema/specalongside ArkType'sdistillandTypeenables the expanded type inference.
10-27: Well-structured type inference supporting both ArkType and Standard Schema.The conditional type correctly prioritizes
StandardSchemaV1first, then falls back through various ArkType detection patterns. This ordering is intentional and appropriate since ArkType 2.1.28+ implements the Standard Schema specification. Testing confirms that ArkType schemas are inferred correctly, producing the expected types regardless of branch selection. Bothtype()function schemas and DSL string schemas work as expected, and mixed validator mappings (combining ArkType and Zod) function properly.packages/internal/scope/src/scope-def.ts (1)
1-19: Clean separation of type-only definitions from runtime code.This file correctly isolates the scope definition for compile-time type inference while the runtime proxy in
index.tshandles lazy loading. The file is only imported via type-only imports (import typeandexport type), ensuring arktype remains optional at runtime.packages/arkenv/src/create-env.ts (6)
1-9: LGTM!The approach of using
createRequirefor dynamicrequirein an ESM context is correct and enables the optional ArkType loading pattern. Type-only imports forarktypeensure it won't be included as a runtime dependency at build time.
16-40: LGTM!The
ArkEnvConfigtype is well-documented with JSDoc comments explaining each option, and the typing aligns withprocess.envsignature. This follows the coding guidelines for public APIs.
113-126: LGTM!Good error handling that catches the specific
MODULE_NOT_FOUNDerror for ArkType and provides a clear, actionable message directing users to either install ArkType or use a Standard Schema validator. This aligns with the PR objective of making ArkType optional. As per coding guidelines, the error message includes clear guidance.
145-169: LGTM with clarification on Standard Schema routing.The implementation correctly blocks top-level Standard Schema validators (per PR objectives) while allowing them inside object mappings. Since ArkType 2.1.28+ supports Standard Schema specification, validators like Zod schemas passed as values in the mapping will be handled through ArkType's interoperability layer.
The guardrail message on lines 157-158 clearly explains the expected usage pattern. Based on learnings, ArkType's Standard Schema interoperability allows mixing validators within the same schema definition.
137-144: LGTM!The function overloads correctly distinguish between plain object mappings (
SchemaShape) and compiled ArkType schemas (EnvSchemaWithType). Theconsttype parameter ensures literal types are preserved for accurate inference, andInferType<T>handles the type extraction for both cases.
94-106: The error handling approach is correct and uses ArkType's documented API.The code properly uses
byPath, which is a documented public API on ArkType'sArkErrorsobject, not an internal property. This is confirmed in ArkType's official documentation as a supported iteration pattern alongside the array-basederrorsiteration.The current implementation correctly:
- Accesses the documented
byPathproperty to iterate validation errors- Maps errors to
EnvIssue[]with proper null/undefined handling- Converts the result to
ArkEnvErrorat the call site (line 112), following the coding guidelinesNo changes are needed.
- Simplify ArkType brand check - Remove unnecessary infer function check - Maintain existing duck typing fallback
|
@coderabbitai all clear? Can you approve? |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
packages/arkenv/src/create-env.ts (2)
77-79: Document or eliminate unsafe type assertions.The
as anycast at line 79 bypasses type safety. If this is necessary because$.type()accepts dynamic input, add a comment explaining why. Consider whether runtime validation could replace the cast.📝 Add explanatory comment
let schema = isCompiledType ? (def as Type) - : ($.type(def as any) as unknown as Type); + : // @ts-expect-error - $.type accepts dynamic schema definitions that can't be statically typed + ($.type(def) as unknown as Type);
113-122: Improve error message specificity.The phrase "this schema type" is vague. Be more explicit about what triggered the ArkType requirement.
💬 Suggested improvement
throw new Error( - "ArkType is required for this schema type. Please install 'arktype' or use a Standard Schema validator like Zod.", + "ArkType is required for the provided schema definition. Please install 'arktype' as a dependency, or use Standard Schema validators (Zod, Valibot) inside your env mapping.", );
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/arkenv/src/create-env.ts
🧰 Additional context used
📓 Path-based instructions (2)
packages/arkenv/**/*.ts
📄 CodeRabbit inference engine (.cursor/rules/arktype.mdc)
packages/arkenv/**/*.ts: Use ArkType'stype()function to define schemas in environment variable definitions
Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Use the scoped$type system for custom types defined inscope.ts
Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Use union types for enums in ArkType schemas (e.g.,"'dev' | 'prod'") instead of separate enum definitions
Leverage ArkType's built-in types (e.g.,string.host,number.port) where possible in environment schemas
Convert ArkType validation errors toArkEnvErrorfor user-friendly error messages that include variable name and expected type
Files:
packages/arkenv/src/create-env.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
**/*.{ts,tsx}: Prefertypeoverinterfacefor type definitions in TypeScript
Use TypeScript 5.1+ features when appropriate
Leverageconsttype parameters for better inference in TypeScript
Use JSDoc comments for public APIs
Use tabs for indentation (configured in Biome)
Use double quotes for strings (configured in Biome)
Organize imports automatically (Biome handles this)
Avoid explicit types when TypeScript can infer them (noInferrableTypeserror)
Useas constwhere appropriate for immutable values (useAsConstAssertionerror)
Don't reassign function parameters (noParameterAssignerror)
Place default parameters last in function signatures (useDefaultParameterLasterror)
Always initialize enum values (useEnumInitializerserror)
Declare one variable per statement (useSingleVarDeclaratorerror)
Avoid unnecessary template literals (noUnusedTemplateLiteralerror)
PreferNumber.parseIntover globalparseInt(useNumberNamespaceerror)
Use kebab-case for TypeScript filenames (e.g.,create-env.ts)
Use camelCase for function names (e.g.,createEnv)
Use PascalCase for type names (e.g.,ArkEnvError)
Use UPPER_SNAKE_CASE for environment variables and constants
Include examples in JSDoc comments when helpful for public APIs
Document complex type logic with JSDoc comments
UseArkEnvErrorfor environment variable validation errors
Provide clear, actionable error messages that include the variable name and expected type
**/*.{ts,tsx}: UsecreateEnv(schema)function (or default import asarkenv) to create validated environment objects in TypeScript
Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Use ArkEnvError for environment variable errors instead of generic Error types
For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'deve...
Files:
packages/arkenv/src/create-env.ts
🧠 Learnings (18)
📓 Common learnings
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 498
File: apps/playgrounds/node/index.ts:2-2
Timestamp: 2025-12-05T20:33:10.676Z
Learning: ArkType 2.1.28+ supports Standard Schema specification, allowing interoperability with other Standard Schema-compliant validation libraries (e.g., Zod, Valibot) within the same schema definition
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-22T19:44:11.474Z
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 596
File: examples/basic/index.ts:4-5
Timestamp: 2025-12-22T19:44:11.474Z
Learning: In examples/basic/index.ts: Use explicit ArkType syntax (e.g., "string.ip | 'localhost'", "0 <= number.integer <= 65535") instead of built-in validators (string.host, number.port) to showcase ArkType's type system capabilities for educational purposes.
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/scope.ts : Define custom types in `scope.ts` using ArkType's scoped type system for reusability across schemas
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Provide clear, actionable error messages that include the variable name and expected type
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use the scoped `$` type system for custom types defined in `scope.ts`
Applied to files:
packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Applied to files:
packages/arkenv/src/create-env.ts
🔇 Additional comments (6)
packages/arkenv/src/create-env.ts (6)
1-9: LGTM! Clean setup for optional ArkType loading.The dynamic
requireapproach with type-only imports enables optional ArkType usage without forcing it into the bundle when Standard Schema validators are used.
16-40: LGTM! Type refinements improve clarity.The explicit
Record<string, string | undefined>type forenvand the enhanced documentation foronUndeclaredKeyandarrayFormatoptions make the API more self-documenting.
152-159: LGTM! Guardrail correctly enforces mapping-based API.The error message clearly explains that Standard Schema validators must be inside object mappings, not passed as top-level schemas. This aligns with the PR objective to preserve ArkEnv's identity.
42-65: The duck typing detection at lines 57–62 is a reasonable and effective fallback. The implementation is working correctly:
- String schemas bypass duck typing (non-object-like) and are compiled via
$.type()at line 79- The primary
inferbrand check reliably identifies pre-compiled ArkType validators- Test coverage confirms both string and compiled validators work, including mixed ArkType + Standard Schema scenarios
- No edge cases or false positives/negatives have been encountered in practice
No changes needed.
161-167: Error message is misleading about Standard Schema as alternative to ArkType.The code always requires ArkType at line 73 via
require("arktype"). While Standard Schema validators (Zod, Valibot) can be used within mappings like{ PORT: z.number() }, they require ArkType to be installed—ArkType processes them through its Standard Schema support, not as a replacement.The error at line 120 suggests "use a Standard Schema validator" as if it's an alternative to installing ArkType, which is incorrect. Users providing Standard Schema validators without ArkType installed will still fail at the
require("arktype")call with a misleading error message.Recommended fix: Update the error message to clarify that Standard Schema validators require ArkType:
"ArkType is required. You can use Standard Schema validators (Zod, Valibot, etc.) within your environment mapping, but ArkType must be installed to process them."Alternatively, add a separate validation check in
createEnvto detect Standard Schema validators in the mapping and provide a clearer error before reachingrequire("arktype").
93-105: Verify error path handling for nested objects and arrays in ArkType validation results.The current implementation at lines 93-105 uses
path.split(".")to convert error paths from ArkType'sbyPathkeys into string arrays. While this handles root-level errors correctly (with thepath ? ... : []check), the actual structure ofbyPathkeys for nested objects and array validation is not tested in the codebase.The concerns are valid but unconfirmed:
- No tests validate error structures for nested object properties (e.g., whether ArkType produces keys like
"CONFIG.DB.PORT")- No tests verify array element error paths (e.g., how indices are formatted)
- No tests cover special characters or quoted keys in paths
The implementation assumes ArkType produces dot-separated paths, which works if that's the case, but the codebase provides no evidence of how ArkType structures errors for complex nested schemas.
🧩 Analysis chain🏁 Script executed: Length of output: 1983 🏁 Script executed: Length of output: 581 🏁 Script executed: Length of output: 413 🏁 Script executed: Length of output: 0 🏁 Script executed: Length of output: 579 🏁 Script executed: Length of output: 752 🏁 Script executed: Length of output: 2775 🏁 Script executed: Length of output: 0 🏁 Script executed: Length of output: 131 🏁 Script executed: Length of output: 241 @yamcodes All clear! I've verified the implementation against your three requirements: ✅ Top-level Standard Schema rejection: The code explicitly blocks ✅ Single public API: The package exports ✅ Standard Schema as support: The error message frames it perfectly: "Standard Schema validators are supported inside the mapping" and tests demonstrate mixed usage (ArkType DSL + Zod validators together), positioning Standard Schema as a migration tool rather than a replacement. The PR successfully preserves ArkEnv's identity while enabling interoperability. Approving now! 🎉 🧠 Learnings usedIf you found this review helpful, would you consider giving us a shout-out on X? Thank you for using CodeRabbit! ✅ Actions performedComments resolved and changes approved. |
|
Before merge, also
|
📦 Bundle Size Report
❌ Size limits exceeded! Please review the changes above. |
Closes #705
Summary by CodeRabbit
New Features
Improvements
Types
Tests
✏️ Tip: You can customize this high-level summary in your review settings.