feat: use namespaces to export "internal" types that are used in exported signatures

[EskiMojo14]

Currently there's no easy way to get the type for "a schema I can pass to this method", as the Schema type for each is internal. This PR uses type-only namespaces to nest the type under the method/action itself, meaning it avoids conflicts but still allows use if needed.

An example of where this would be useful:

import * as v from 'valibot'

export class TypedHttpClient<T extends v.partial.Schema> {
  constructor(private schema: T) {}

  get(someUrl: string, selectFields: string[]) {
    const rawData = null; // fetch data with includeFields

    const partialSchema = v.partial(this.schema);

    const output = v.parse(partialSchema, rawData);
  }
}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
valibot	Ready	Preview	Comment	Sep 16, 2025 11:14am

[ahrjarrett]

Cool PR!

If you change these to ambient namespaces it will enforce that no values are added to these namespaces. It will also help with the erasableSyntaxOnly flag

Suggested change

	export namespace args {
	export declare namespace args {

[EskiMojo14]

hmm, I'm still allowed to do export const in an ambient namespace

erasableSyntaxOnly is a good shout, worth checking if anything valibot is doing violates that

[EskiMojo14]

ah, though that was added in TS 5.8 and this repo is currently on 5.7.3

[ahrjarrett]

I tend use ambient namespaces by default. And if Valibot uses 5.7.3, in userland if an enum or value-level namespace is used, it can't be erased for users that are on later versions of TS

[EskiMojo14]

just checked - no source code uses enums, but there are some used in tests for schemas that support native enums

[ahrjarrett]

To clarify -- if you write export const x = 1 in an ambient namespace, the namespace and x will be erased at runtime.

If you write export const x = 1 in a regular namespace, then namespace won't be erased, and x will be shipped with the JS bundle

[EskiMojo14]

yes, but the const is still in the type declarations so as far as typescript is concerned it exists, which seems worse imo

[ahrjarrett]

If that's a concern, then I recommend this:

export declare namespace args {
  export type { Schema }
}

type Schema = // ...

That way there's no pattern of adding anything to the namespace itself. It also allows users to access Schema in both places

[EskiMojo14]

i think I'd rather leave it as is, and maybe we get a follow up PR for updating TS and enabling erasableSyntaxOnly if that's desired

[ahrjarrett]

The diff would be much smaller that way too 🤷 it can only help your chances of getting it merged