Skip to content

api-stability.md

Latest commit

 

History

History
428 lines (363 loc) · 18.1 KB

api-stability.md

File metadata and controls

428 lines (363 loc) · 18.1 KB
Raw

API Stability

Current Status

GoFrame is experimental. APIs, GOX syntax, manifests, and toolchain behavior may still change between previews.

This document classifies current surfaces so future changes can be discussed with clear expectations. It does not create a stable 1.0 compatibility promise.

Stability Tiers

Public-Candidate

Intended direction for user-facing APIs. Changes should include migration notes, tests, and a compatibility reason.

Experimental Frontier

Can change between previews. Changes should be documented, but migration support is best-effort. Experimental frontier surfaces are real working surfaces, not hidden or deprecated features; they need more contract hardening before broad preview promises.

Compiler-Facing / Low-Level

Exported for GOX, goxc, generated-code-like use, or third-party tooling. These surfaces are not the preferred high-level app authoring path unless explicitly documented.

Internal

Runtime, compiler, toolchain, or smoke-test implementation details. These are not user APIs and may change without compatibility guarantees.

Future Vision

Strategic direction that should remain visible but is not a current preview promise.

Legacy / Deprecated

Kept temporarily for migration or compatibility. New code should avoid these surfaces.

Compatibility Policy

During the current pre-1.0 preview line:

  • compatibility is important but not absolute;
  • breaking changes are allowed when they remove unsafe behavior, simplify a wrong API, or unblock the architecture;
  • breaking changes should be documented in CHANGELOG.md and relevant docs;
  • generated output and hidden workspace internals are not stable.

This policy should be revisited and tightened before a stable 1.0 release.

Current API Classification

User-Facing Public-Candidate

Runtime:

  • gf.Node
  • gf.Component
  • gf.C
  • gf.NewComponentType
  • gf.ComponentT
  • gf.UseState
  • gf.UseReducer
  • gf.UseEffect
  • gf.UseUnmount
  • gf.Deps
  • gf.Once
  • gf.EveryRender
  • gf.CreateContext
  • gf.ProvideContext
  • gf.UseContext
  • gf.UseContextSelector
  • props-level MemoEqual convention
  • gf.VirtualList
  • gf.VirtualTable
  • gf.RoutePath
  • gf.NotFoundRoute
  • gf.NewHashRouter
  • gf.RouterView
  • gf.RouterLink
  • gf.Navigate
  • gf.HashHref
  • gf.QueryValues
  • gf.ParseQuery
  • gf.WithQuery
  • gf.ResourceStatus
  • gf.Resource
  • gf.ResourceLoader
  • gf.UseResource
  • gf.ErrorBoundary
  • gf.ErrorBoundaryProps
  • gf.ErrorBoundaryContext
  • basic event facades such as gf.Event, gf.InputEvent, and gf.ScrollEvent
  • generated typed component identity contracts

Tooling:

  • goxc check
  • goxc generate
  • goxc build
  • goxc package
  • goxc inspect
  • goxc export
  • goxc serve
  • goxc dev
  • goxc size
  • goxc doctor
  • goxc clean
  • goxc version

These are public-candidate because examples and docs rely on them, but their exact shapes can still change before stable 1.0.

The high-level goxc dev contract is a loopback-only development server over verified completed full-package generations. Failed post-start builds preserve the last successful generation and present the failure in connected browsers; successful recovery activates a completed generation and triggers the normal full-page reload. Polling intervals, quiet-period timing, reload transport internals, and terminal wording are not compatibility contracts. goxc dev does not establish HMR, browser state preservation, incremental compilation, source maps, clickable diagnostics, or production hosting.

The goxc check --format=json schema version 1 transport is a versioned tooling process contract. Consumers should reject unsupported schema versions, and incompatible field or semantic changes require a schema version increment. The official lightweight VS Code extension consumes this contract for CLI-backed source diagnostics. Exact diagnostic wording remains experimental, and this editor integration does not create an LSP compatibility promise.

The separate goxc inspect --format=json schema version 1 report is also a versioned tooling process contract. It describes the declared graph of one existing current standalone package with deterministic package-relative paths. Its path fields and edge endpoints are canonical slash-only package paths; artifact.logicalName is instead a canonical generated namespace key. A drive-looking prefix can be key data while remaining invalid at the start of a package path. The report does not promise that every producer-supported filename is portable across host filesystems. Incompatible field or semantic changes require a schema version increment. The default text report is human-facing and its exact formatting remains experimental; consumers should parse JSON rather than text.

Exported Compiler-Facing / Low-Level

Runtime helpers:

  • gf.El
  • gf.Text
  • gf.Fragment
  • gf.Empty
  • gf.Child
  • gf.Key
  • gf.WithKey
  • gf.Props
  • gf.If
  • gf.IfElse
  • gf.Map
  • gf.MapIndexed
  • gf.ToString
  • node structs such as gf.VNode, gf.TextNode, gf.FragmentNode, gf.EmptyNode, and gf.KeyedNode

These remain exported because GOX-generated code and handwritten low-level Go need them. Most application authors should prefer GOX markup for structure.

Compiler package:

  • gox.Generate
  • gox.GenerateNamed
  • gox.GenerateWithOptions
  • gox.GenerateOptions
  • gox.PackageSource
  • gox.PackageGenerateOptions
  • gox.GeneratePackageWithOptions
  • gox.GenerateFile
  • gox.GenerateFileTo
  • gox.GenerateFileToWithOptions
  • gox.FindFiles
  • gox.Codegen
  • gox.ParseElement
  • gox.Diagnostic
  • gox.DiagnosticError

These are exported for the toolchain, editor integrations, and tests. Generate, GenerateNamed, and GenerateWithOptions are the primary in-memory generation boundary for callers that choose their own source bytes. PackageSource, PackageGenerateOptions, and GeneratePackageWithOptions provide coordinated in-memory generation for callers that already possess the complete GOX source set for one Go package. goxc currently uses this boundary to reserve matching authored package-level declarations and allocate deterministic collision-safe private component identifiers before rendering each GOX output. The caller supplies the GOX sources, optional authored Go package sources, and one package identity value; an empty identity uses the existing Go package-name fallback. All GOX entries in one call must declare the same package. The API checks their package names, rejects duplicate Filename values, and sorts inputs before allocation. PackageSource.Filename is the source identity used during coordination, the filename used in diagnostics, and the key in the returned map[string][]byte. The result contains generated bytes for GOX inputs only; Go map iteration order is not defined. Authored sources are parsed only to reserve package-level identifiers from sources whose package name matches the GOX package. They are not transformed or returned as generated output.

The package generation API does not discover packages, walk directories, resolve modules, interpret build constraints, select platform-specific files, validate source-root ownership, reject filesystem symlinks, enforce output-root containment, or publish package artifacts. Callers supply the intended complete package source set and any required package-selection or filesystem policy; goxc provides its own discovery and root-aware filesystem safety around this boundary. Exact generated component variable names, collision suffixes, and allocation choices remain internal implementation details. These declarations are compiler-facing and experimental before stable 1.0. Third-party compiler or editor tooling may call them, but their option and result shapes may change with compiler needs. Such changes should be documented and tested; this surface does not establish a stable package-loader, build-system, or language-service compatibility promise.

GenerateFile, GenerateFileTo, GenerateFileToWithOptions, and FindFiles are trusted-filesystem convenience helpers for tooling/editor/test workflows. They use ordinary standard-library file operations and do not inherit goxc's root-aware symlink rejection, physical output-overlap checks, package ownership checks, or package publication guarantees. Use goxc or add a caller-side filesystem policy when processing untrusted repository trees.

Diagnostics and file generation are tooling contracts. The AST, lexer, and parser structs are exported today but should be treated as compiler-facing and experimental rather than stable user APIs.

Tooling contracts:

  • goframe.json user-authored manifest input, including preview-facing "assets": "./assets" directory mode and legacy explicit asset lists;
  • asset-manifest.json generated package metadata and companion entrypoint manifest;
  • goframe-package.json generated package metadata and authoritative current package completion/ownership marker;
  • GOFRAME_WORKSPACE / --workspace external workspace override;
  • default hidden .goframe workspace behavior.

VS Code extension:

  • syntax highlighting, snippets, command wrappers over goxc, and CLI-backed schema-v1 source diagnostics are experimental editor tooling contracts, not language-server stability promises. LSP and formatter behavior remain outside the current contract.

Experimental Frontier

  • GOX syntax surface.
  • GOX expression ergonomics.
  • GOX package-qualified component tags (packageAlias.Component).
  • Component boundary API shape that is already public-facing (for example gf.ComponentT and typed identity tokens) can still have experimental semantics in specific lifecycle, remount, and edge-case compatibility areas. The exported surface is documented for preview usage, while deep behavior under module/version/package-path edge cases remains experimental and outside the current preview promise.
  • GOX diagnostic wording beyond the filename/line/column/source-line contract.
  • Context topology behavior and selector limitations.
  • Virtualization details such as fixed-height range buffering and table spacer structure.
  • Component identity id format for generated GOX component tokens.
  • Runtime error reporting API and exact phase containment behavior: gf.SetErrorHandler, gf.ErrorInfo, gf.ErrorHandler, and gf.ErrorPhase. Current tests cover event, effect, cleanup, memo, context, virtual callback, render, and boundary-related reporting paths, but this is still not a production error framework.
  • Scoped render Error Boundary reset/fallback semantics beyond the current public-candidate API shape. Internal boundary phases such as protected, captured, and fallback are not public API. Current tests cover containment, nested fallback bubbling, reset, ResetKey, pending effect cancellation, and cleanup release for failed subtrees.
  • Component-scoped resource API and exact lifecycle semantics: gf.ResourceStatus, gf.Resource, gf.ResourceLoader, and gf.UseResource. Current tests cover loading/ready/failed state, reload, key changes, stale completions, cleanup, loader panic containment, and ErrorBoundary interaction. Global caching, deduplication, retry policy, route loaders, and Suspense-style semantics are outside the preview contract.
  • Experimental browser text fetch helper: gf.FetchText. It is a low-level ResourceLoader[string]-compatible helper for browser/WASM text responses. It does not establish JSON loading, route loader, cache, retry, server API, SSR, hydration, or production server contracts.
  • Hash router details such as route remount policy, declaration-order matching edge cases, link props, query helper edge cases, and browser listener internals. Current tests cover route matching, params, query helpers, not-found fallback, hash hrefs, and route subtree keys by route pattern; browser back/forward and listener behavior are covered by smoke tests rather than a stable low-level listener API.
  • Form and validation patterns. MVP 25 documents controlled-input patterns but intentionally does not add a runtime form framework.
  • Package manifest field stability.
  • Browser smoke scripts and debug probe output.
  • VS Code extension commands, snippets, and CLI-backed diagnostics behavior.
  • goxc dev watcher timing; reload and build-error event names; private JSON payload fields; presentation DOM, CSS, and build-number formatting; and reload/error broker storage below the documented high-level command behavior.
  • pkg/gox AST/lexer/parser structures.

These surfaces should be hardened, tested, and documented before wider promises. They should not be removed from project positioning merely because their contracts are still maturing.

Inactive Or Outside Current Contract

  • Player/Engine host and bundle model: inactive direction.
  • .gfapp package format: inactive direction.
  • Portable host/runtime story beyond the browser DOM target: inactive direction.
  • Fullstack/backend integration: not a current feature claim.
  • Stronger editor tooling such as LSP/formatter behavior: outside the current preview contract.
  • Broader package ecosystem and reusable component distribution story: outside the current preview contract.
  • Production deployment/server integration: outside the current preview contract.

These are not part of the current preview promise.

Internal

  • dirty queue internals;
  • mounted tree structures;
  • component instance fields;
  • state/effect/context slot storage;
  • virtual range helper functions;
  • .goframe/work, .goframe/build, .goframe/package, and .goframe/cache internal layout;
  • .goframe/gen generated file layout;
  • debug globals and browser probe object shapes;
  • package staging directories;
  • smoke harness implementation details.
  • generated component variable names;
  • exact generated .goframe/gen filenames;
  • browser debug global object shapes;
  • package/export staging temporary directories.
  • private inspect report structs, filesystem traversal, sorting and SHA helper implementations, and package-root resolution details below the documented command behavior;
  • build-tagged document metadata coordinators, candidate adapters, fixture telemetry, and transactional ownership research symbols;

Legacy / Deprecated

  • goxc build --release: accepted temporarily, but package/compress behavior belongs to goxc package.
  • Explicit "wasm": "main.wasm" manifests: still supported, but examples and docs use bundle.wasm.
  • Explicit asset list manifests such as "assets": ["index.html"]: still supported, but examples and docs use "assets": "./assets".
  • Legacy manifest.json package marker: fail-closed migration support only for the historical GoFrame package manifest shape; goframe-package.json is current.
  • goxc generate --in-place: debug/legacy only. Generated .gox.go files should live under .goframe/gen or an explicit output directory.
  • UseMount: deprecated alias for once-after-mount effect behavior.
  • NoDeps: deprecated alias for Once.
  • AlwaysDeps: deprecated alias for EveryRender.
  • DepsOf and Dep* explicit helpers: retained for compatibility; prefer Deps.
  • For and ForIndexed: deprecated aliases for Map and MapIndexed.

Questionable APIs And Decisions

Surface Decision Rationale
Component vs ComponentT Keep both. Component preserves handwritten compatibility; generated GOX uses typed identity.
El/Text/Fragment/Props Compiler-facing but available. Needed by generated code and low-level Go; GOX remains the recommended authoring path.
UseMount/deps aliases Deprecated, not removed. Existing code may use them; replacement APIs are already present.
ErrorHandler and ErrorBoundary Experimental/Public-Candidate split. Useful and tested, but full route-level/error-boundary policy is not final.
Resources Experimental. Component-scoped lifecycle and the text-only gf.FetchText helper are tested, but no global cache, Suspense, JSON/data framework, or route loader contract exists.
Router query helpers Public-Candidate with limitations. Good for simple URL state; not a typed query-state manager.
Virtualization Public-Candidate fixed-height contract. Dynamic measurement and advanced accessibility remain future work.
pkg/gox parser/AST exports Compiler-facing experimental. Exported today for tooling/tests, but not a stable language-service API.
pkg/gox package generation API Compiler-facing experimental. Needed by goxc for deterministic package-wide generated identifier allocation; callers supply the complete package source set and must not depend on exact generated names or long-term option/result shape.
pkg/gox file helpers Trusted-filesystem convenience. Useful for editor/test tooling; hardened untrusted filesystem handling belongs to goxc or caller-side policy.

Deprecation Policy

For now, deprecations should:

  • keep a clear warning or documentation note;
  • have a replacement path;
  • remain covered by tests if behavior is still accepted;
  • be removed only in a documented cleanup stage.

What Is Not Stable Yet

Not stable:

  • path/history-mode routing and server fallback behavior;
  • file-based routing, route loaders, route middleware, and route-level error boundary policy;
  • schema validation or a form framework;
  • global resource cache, higher-level transport helpers, route loaders, and Suspense-style resource story;
  • SSR/hydration;
  • Player/Engine or .gfapp format;
  • portable host/runtime packaging;
  • fullstack/server APIs;
  • multi-module app support;
  • final public component package identity policy;
  • dynamic virtualization measurement;
  • infinite loading;
  • advanced accessibility/keyboard model for tables;
  • LSP/formatter behavior;
  • stable callback hook;
  • full Error Boundary model beyond scoped render fallback and reset;
  • automatic route-level Error Boundaries;
  • production deployment server behavior.

Current Preview Boundaries

The current preview does not claim:

  • broad multi-module workspace identity;
  • stable reusable component package identity across independently versioned modules;
  • equivalent Firefox/Safari/browser engine evidence;
  • production deployment/server behavior;
  • 1.0 API compatibility.