perf(core): claw back ~0.85 kB gzip vs v0

[yamcodes]

Context

@arkenv/core@1.0.0-alpha.9 is ~3.1 kB gzip / ~7.5 kB min vs v0 arkenv@0.12.3 ~2.3 kB gzip / ~5.7 kB min (Bundlephobia; arktype peer excluded). size-limit was raised 2.2 → 2.9 kB.

This is the v1 @arkenv/core package (v1 branch), not the old v0 arkenv/core ~441 B ArkEnvError stub.

The delta is always-on in the default import arkenv path: issue objects, pretty-print, secret redaction, { safe: true }, and CLI schema-capture. Not source maps, dual CJS/ESM, or arktype.

Keep (out of scope)

• Coercion (already in v0)
• Keywords (string.host / number.port)
• Pre-coerce copy so process.env is not mutated (fix: Simplify coercion: unify ArkType and Standard Schema paths with pre-coercion model #1193)
• Secret redaction in error text (default-on)

Realistic target after the cuts below: ~2.5 kB gzip. Hitting 2.0 would mean dropping redaction or EnvIssue — don't.

Subtasks

• Pull CLI schema-capture (Symbol.for("arkenv.schemaCapture.v1"), feat: CLI schema loader — safely import a user's env.ts and expose its declared keys #1622) out of the default arkenv() path. CLI-only entry or subpath so production imports don't pay for it (~330 B min plus capture branches).
• Stop re-exporting formatIssues / getSchemaKeys from the main @arkenv/core barrel (move to a subpath, e.g. @arkenv/core/issues). Set "sideEffects": false on the package (currently unset; Bundlephobia reports hasSideEffects: true). size-limit and Bundlephobia import "*", so extra barrel exports inflate the published number; real apps also cannot tree-shake today.
• Split { safe: true } (safeExecute, buildEnvIssue, (v1) Unify error normalization and formatting #1157) to an opt-in subpath (@arkenv/core/safe or named tryArkenv) so the throw path does not include result-object machinery.
• Re-measure: size-limit + Bundlephobia (or esbuild minify+gzip of dist/index.mjs, ignore arktype). Confirm ~2.5 kB gzip and that redaction / coercion / keywords still work on the default export.

Notes

• minify: false on publish is a Nuxt rebundle constraint (docs(v1): Simplify Docs (tracking) #1527). Bundlephobia minifies itself; this does not explain the gzip gap.
• Maps were already dropped in alpha.9 (perf: reduce package install sizes monorepo-wide by omitting maps and externalizing core types #1734) — install size only.

[pullfrog]

Evaluation: actionable

Verified against @arkenv/core@1.0.0-alpha.9 on the v1 branch (worktree):

• tsdown.config.ts bundles @repo/utils (deps.alwaysBundle) into a single src/index.ts entry; size-limit measures import "*" → every barrel re-export/import is retained in dist/index.mjs.
• src/arkenv.ts imports isCapturingSchema/recordSchemaCapture (whole schema-capture.ts module: begin/end/getState + Symbol.for("arkenv.schemaCapture.v1"), ≈ the ~330 B the issue cites) and safeExecute, all always-on in the throw path.
• src/index.ts re-exports formatIssues + getSchemaKeys; getSchemaKeys → schema.ts is referenced nowhere else in core's parse path, so it can't tree-shake under import "*".
• sideEffects is unset in packages/core/package.json → Bundlephobia hasSideEffects: true.
• Consumers of the barrel exports: @arkenv/nextjs (getSchemaKeys in src/index.ts + src/react-server.ts), docs (apps/www/content/docs/reference/core.mdx), and core's own errors.test.ts. The CLI + nuxt already import these from @repo/utils; @arkenv/standard re-exports from @repo/utils and stays ArkType-free.

Plan

M1 — Capture out of the default path (~330 B min)
In src/arkenv.ts, replace the isCapturingSchema()/recordSchemaCapture branch with a self-contained inline probe on the same global bag:
const state = (globalThis as any)[Symbol.for("arkenv.schemaCapture.v1")]; if (state?.capturing) { state.definitions.push(def); return {}; }
schema-capture.ts then tree-shakes out of the core chunk while the CLI's existing @repo/utils beginSchemaCapture/endSchemaCapture (same symbol, same bag shape) keeps working with zero CLI churn. Keep src/schema-capture.test.ts and the CLI jiti-schema-loader/check capture tests as the regression net. (Alternative strict @arkenv/core/capture subpath + jiti alias recommended against: require.resolve/version-skew machinery for ~identical savings.)

M2 — Barrel slimming + sideEffects

• New src/issues.ts entry exporting formatIssues, getSchemaKeys + EnvIssue/EnvIssueCode/EnvIssueMeta; add "./issues" to the exports map (types/import/require) and a tsdown entry. Remove both from the main barrel (ArkEnvError keeps working — it calls formatIssues internally).
• Repoint @arkenv/nextjs import { getSchemaKeys } → @arkenv/core/issues.
• Set "sideEffects": false in packages/core/package.json.
• Update errors.test.ts, test/dist.test.ts (subpath coverage), and apps/www/content/docs/reference/core.mdx (exports table).

M3 — Split { safe: true }

• New src/safe.ts entry exporting tryArkenv(def, config?) (name TBD; @arkenv/core/safe subpath) = safeExecute(() => parse(...)) → SafeArkEnvResult.
• Main arkenv(): drop the safe: true overloads + if (config.safe) branch + safeExecute import. Keep ArkEnvConfig.safe?: false for call-site compat and SafeArkEnvResult as a type-only export.
• Remove redundant safe: false call sites: nextjs arkenv-internal.ts (x2), nuxt boot-gate.ts, validate-schema.ts.
• Move the { safe: true } cases in core errors.test.ts/standard-mode.test.ts into a subpath-targeting safe.test.ts. Breaking API partition → changeset note (right place, v1 alpha).

M4 — Re-measure + land

• pnpm --filter @arkenv/core... build, then pnpm --filter @arkenv/core size; re-record .size-limit.json and lower the limit from 2.9 kB toward ~2.4–2.5 kB. Confirm redaction / coercion / keywords still pass on the default export.
• Changeset on @arkenv/core (fixed-grouped with @arkenv/standard; only core changes).
• Verify: core/standard/nextjs/nuxt/CLI suites, pnpm exec turbo run typecheck --filter=@arkenv/core, pnpm check.

Trade-off: Agree 2.0 kB isn't worth dropping redaction or EnvIssue. Note the safe split's byte win is modest (one small function in an already-bundled module); it's most valuable for branch locality + API clarity, so it's the first cutoff if the scope needs shrinking.

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Claw ~0.85 kB gzip off the default @arkenv/core import versus v0, without dropping redaction, coercion, or keywords.

Current behavior:
Default import arkenv from "@arkenv/core" always pays for CLI schema-capture helpers, { safe: true } result-object machinery, and barrel re-exports of formatIssues / getSchemaKeys. sideEffects is unset, so bundlers treat the package as having side effects. Published size is ~3.1 kB gzip / ~7.5 kB min (@arkenv/core@1.0.0-alpha.9) versus v0 arkenv@0.12.3 ~2.3 kB gzip / ~5.7 kB min; size-limit is 2.9 kB. size-limit and Bundlephobia measure import "*", so extra barrel exports inflate the published number.

Desired behavior:

1. Schema capture out of the default path. The default arkenv() parse path must not import the capture helper module. It may probe the existing Symbol.for("arkenv.schemaCapture.v1") global bag inline (same bag shape the CLI already uses via beginSchemaCapture / endSchemaCapture from @repo/utils) and, when capturing is set, push the definition and return a dummy object. CLI capture behavior is unchanged. Do not add an @arkenv/core/capture subpath or jiti alias.

2. Barrel slimming. formatIssues, getSchemaKeys, and the EnvIssue / EnvIssueCode / EnvIssueMeta types live on an @arkenv/core/issues subpath (types / import / require). The main barrel must not re-export them. ArkEnvError still formats issues internally. @arkenv/nextjs imports getSchemaKeys from @arkenv/core/issues. Set "sideEffects": false on @arkenv/core. Docs export table and dist/subpath tests cover the new entry.

3. Split { safe: true }. Throw-path arkenv() no longer includes result-object machinery (safeExecute / buildEnvIssue on the default path). Opt-in @arkenv/core/safe exports tryArkenv(def, config?) returning SafeArkEnvResult. Keep ArkEnvConfig.safe?: false for call-site compat; SafeArkEnvResult may remain a type-only export from the main entry. Drop redundant safe: false call sites. Move { safe: true } tests onto the subpath. This is a breaking API partition in v1 alpha — changeset it. If scope must shrink, this milestone is the first cutoff (byte win is modest; value is branch locality).

4. Re-measure. After the cuts, size-limit on @arkenv/core should land around ~2.4–2.5 kB gzip (lower the current 2.9 kB budget). Default export still redacts secrets, coerces, and accepts keywords (string.host / number.port). Changeset @arkenv/core (fixed-grouped with @arkenv/standard; only core changes).

Key interfaces:

• Symbol.for("arkenv.schemaCapture.v1") global bag — { capturing, definitions } — CLI and core must keep sharing this contract
• @arkenv/core main export — throw-path arkenv(), no formatIssues / getSchemaKeys re-exports, ArkEnvConfig.safe not true
• @arkenv/core/issues — formatIssues, getSchemaKeys, EnvIssue, EnvIssueCode, EnvIssueMeta
• @arkenv/core/safe — tryArkenv(def, config?) → SafeArkEnvResult
• @arkenv/nextjs — getSchemaKeys from @arkenv/core/issues
• @arkenv/core "sideEffects": false

Acceptance criteria:

• Default @arkenv/core chunk does not include the schema-capture helper module; CLI schema capture still works via the shared symbol bag
• formatIssues / getSchemaKeys are not importable from @arkenv/core and are importable from @arkenv/core/issues
• @arkenv/nextjs compiles against @arkenv/core/issues for getSchemaKeys
• "sideEffects": false is set on @arkenv/core
• Default arkenv() throw path has no { safe: true } branch; tryArkenv (or equivalent) lives on @arkenv/core/safe
• size-limit for @arkenv/core is lowered toward ~2.4–2.5 kB gzip; redaction, coercion, and keywords still pass on the default export
• Changeset on @arkenv/core (fixed-grouped with @arkenv/standard)
• Core / standard / nextjs / nuxt / CLI suites and core typecheck pass

Out of scope:

• Dropping secret redaction or EnvIssue to chase 2.0 kB
• Changing coercion or keywords (string.host / number.port)
• Pre-coerce copy so process.env is not mutated
• Adding @arkenv/core/capture
• Dual CJS/ESM, source maps, or the arktype peer

Triage: Pullfrog evaluated this as actionable on v1 against @arkenv/core@1.0.0-alpha.9. Plan adopted as this brief (inline capture probe; no capture subpath). Moving needs triage → ready for agent.