RFC: Namespaced APIs

[anusree-bruno]

We want to improve the discoverability and structure of the scripting APIs by introducing namespaces instead of keeping everything at the top level of bru.

This will:

• Improve autocomplete relevance by grouping related APIs
• Improve predictability
• Provide a scalable structure for future APIs

This RFC proposes two possible namespaced designs to replace the current environment-related APIs.

Proposal 1 - Unified Namespace:
All environment APIs are grouped under bru.env, with sub-namespaces for collection, global, etc .

Proposal 2 - Split Namespaces:
Environment types are exposed as separate top-level namespaces (bru.env, bru.globalEnv, ...).

Purpose	Current API	Proposal 1 – Unified Namespace	Proposal 2 – Split Namespaces
Get collection env var	bru.getEnvVar(key)	bru.env.collection.get(key)	bru.env.get(key)
Set collection env var	bru.setEnvVar(key, value, options)	bru.env.collection.set(key, value, options)	bru.env.set(key, value)
Delete collection env var	bru.deleteEnvVar(key)	bru.env.collection.delete(key)	bru.env.delete(key)
Check exists	bru.hasEnvVar(key)	bru.env.collection.has(key)	bru.env.has(key)
Get env name	bru.getEnvName()	bru.env.collection.name()	bru.env.name()
Get global env var	bru.getGlobalEnvVar(key)	bru.env.global.get(key)	bru.globalEnv.get(key)
Set global env var	bru.setGlobalEnvVar(key, value)	bru.env.global.set(key, value)	bru.globalEnv.set(key, value)
Get process env var	bru.getProcessEnv(key)	bru.processEnv.get(key)	bru.processEnv.get(key)

We’d love your thoughts on:

• Which API structure do you prefer? Current API, Proposal 1, or Proposal 2?
• Does the naming feel intuitive?
• Any alternative structures you'd propose?