Skip to content
timbl

API Tiers

Every exported symbol has a tier. The tier tells you how much stability you get and how much churn to expect across releases.

stable

The default surface for application authors. These symbols are covered by semver and will not break without a major version bump.

  • defineCMS, defineCollection, defineGlobal, definePlugin from the timbl package
  • createCmsRuntime, startCms and their documented options
  • The built-in field types and their documented options
  • Documented adapter contracts (AuthAdapter, DatabaseAdapter, StorageAdapter, HttpAdapter) when used through the documented factory functions
  • The HTTP API request and response shapes
  • The @timbl/client method signatures
  • Documented error codes from @timbl/core ErrorCodes

If you import only stable symbols, a minor or patch upgrade should not require code changes. Deprecations follow the lifecycle described in the repo docs/governance/semver.md file.

advanced

Lower-level contracts from @timbl/core used by adapter and plugin authors. These are public, typed, and tested, but they expose internal machinery that most application authors never need.

  • The raw HookMap, HookContext, and hook runner types
  • FieldTypeDefinition and the field type registration contract
  • The registry build types and plugin loader contract
  • InferCMS, InferCollection, and the type inference machinery

advanced symbols can change between minor versions when the change is necessary and the migration path is documented. If you build adapters or plugins, you will use these. If you build applications, you usually will not.

unsafe

Raw escape hatches exposed under the unsafe namespace. These give direct access to the database driver, the underlying HTTP app, and other internals that the runtime normally wraps.

// Example shape, see runtime types for exact API
runtime.unsafe.db.raw(...)
runtime.unsafe.app

unsafe exists for cases where the documented adapter surface cannot express what you need: a one-off migration, a driver-specific query, a custom health check reaching into the HTTP layer. Use it sparingly. It can change in any release, including patches. Code that depends on unsafe should pin an exact version and carry its own tests.

internal

Non-exported runtime modules under packages/timbl, registry and handler internals, and anything not documented in these pages. internal symbols have no stability contract. They can be renamed, moved, or removed in any release. Importing them means you are coupled to implementation details, not contracts, and upgrades will break your code.

How to tell which tier you are using

  • If it is documented here or in a package README, it is stable or advanced. The page will say which.
  • If it is exported from @timbl/core and is a type or contract used by plugin authors, it is advanced.
  • If you reached for it via runtime.unsafe, it is unsafe.
  • If you imported it from a path that is not in the package exports map, it is internal.

See also