From 31dcc38c8c437ebcbb356e66214ae4448085b8ab Mon Sep 17 00:00:00 2001 From: Jeremy Andrews Date: Tue, 15 Sep 2026 14:34:38 -0400 Subject: [PATCH] docs: update Dart SDK sources and add client beta guide Signed-off-by: Jeremy Andrews --- docs/reference/sdks/client/dart.mdx | 115 +++++++++++++++++++++++ docs/reference/sdks/server/dart.mdx | 62 +++++++----- src/datasets/sdks/dart-client.ts | 14 +++ src/datasets/sdks/dart.ts | 3 +- src/datasets/sdks/index.ts | 2 + src/datasets/sdks/sdk-compatibility.json | 4 +- 6 files changed, 173 insertions(+), 27 deletions(-) create mode 100644 docs/reference/sdks/client/dart.mdx create mode 100644 src/datasets/sdks/dart-client.ts diff --git a/docs/reference/sdks/client/dart.mdx b/docs/reference/sdks/client/dart.mdx new file mode 100644 index 000000000..5c5afd6f8 --- /dev/null +++ b/docs/reference/sdks/client/dart.mdx @@ -0,0 +1,115 @@ +--- +title: OpenFeature Dart SDK +sidebar_label: Dart +--- + + + +# OpenFeature Dart Client SDK +This package is the vendor-neutral OpenFeature SDK for Dart client +applications. It uses the static-context paradigm. It has no Flutter or +`dart:io` dependency. + +The package is in beta. The first beta defines the public client and provider +contracts. It provides synchronous typed evaluation, event handlers, hooks, +ordered context changes, and an in-memory provider. Later beta changes will +complete the remaining conformance work before the first stable release. + +## Install + +The published beta requires Dart 3.12.2 or later within Dart 3.x. Flutter +applications need a Flutter release that includes a compatible Dart SDK. + +```yaml +dependencies: + openfeature_dart_client_sdk: ^0.0.1-beta.1 +``` + +Run `dart pub get`, or `flutter pub get` in a Flutter application. + +## Use the client + +```dart +import 'package:openfeature_dart_client_sdk/openfeature_dart_client_sdk.dart'; + +Future main() async { + final provider = InMemoryProvider({ + 'new-checkout': true, + 'welcome-message': 'Hello', + }); + + await OpenFeatureAPI.instance.setProviderAndWait(provider); + await OpenFeatureAPI.instance.setEvaluationContextAndWait( + EvaluationContext(targetingKey: 'user-123'), + ); + + final client = OpenFeatureAPI.instance.getClient('checkout'); + final enabled = client.getBooleanValue('new-checkout', false); + final message = client.getStringValue('welcome-message', 'Welcome'); + + print('$enabled: $message'); + await OpenFeatureAPI.instance.shutdown(); +} +``` + +## Implement a provider + +Implement `FeatureProvider` with synchronous resolvers. A resolver must use +local state. It must not perform network, file, or platform-channel I/O. + +Implement only the optional capabilities that the provider needs: + +- `InitializableProvider` for asynchronous initialization. +- `ContextReconciliationProvider` for static-context changes. +- `ShutdownProvider` for resource cleanup. +- `ProviderEventSource` for provider lifecycle events. +- `DomainScopedProvider` when one provider instance supports one domain. +- `TrackingProvider` for non-blocking tracking. + +An initializable or reconciling provider must also implement +`ProviderEventSource`. It must emit the terminal lifecycle event before its +method terminates. The SDK bounds lifecycle waits to 30 seconds by default so +a provider contract violation cannot indefinitely block context changes or +shutdown. Tests and isolated integrations may select a shorter timeout through +`createIsolatedOpenFeatureAPI(lifecycleTimeout: ...)`. + +When initialization or context reconciliation times out, the SDK quarantines +and detaches that provider instance. Its underlying asynchronous work cannot be +cancelled safely, so applications must register a new provider instance rather +than retrying the timed-out one. Subscription cancellation and shutdown cleanup +are bounded by the same timeout. + +A provider that implements `ContextReconciliationProvider` can have only one +active API/domain binding. Use a separate provider instance for each static +context. Providers that resolve entirely from the context passed to each +resolver and do not reconcile cached state may be shared across domains. + +The server and client packages share the +[`open-feature/dart-sdk`](https://github.com/open-feature/dart-sdk) repository. +The repository rename preserves this package name, Dart imports, and independent +client releases. + +## Scope + +This package does not include an HTTP transport, an OFREP provider, a vendor +provider, persistent storage, or Flutter APIs. + +## Validate the package archive + +Run the repository staging command to create and validate the same isolated +client archive used by the publication workflow: + +```text +dart tool/stage_client_package.dart --dry-run +``` + +See the +[beta release procedure](https://github.com/open-feature/dart-sdk/blob/main/doc/client-sdk-release.md) +for the first-publication bootstrap and later automated prereleases. diff --git a/docs/reference/sdks/server/dart.mdx b/docs/reference/sdks/server/dart.mdx index 14774074d..9c76abd01 100644 --- a/docs/reference/sdks/server/dart.mdx +++ b/docs/reference/sdks/server/dart.mdx @@ -4,12 +4,12 @@ sidebar_label: Dart ---

@@ -17,8 +17,8 @@ Last updated at Fri Aug 28 2026 12:00:12 GMT+0000 (Coordinated Universal Time) Specification - - Release + + Release @@ -33,25 +33,39 @@ Last updated at Fri Aug 28 2026 12:00:12 GMT+0000 (Coordinated Universal Time) API Reference - - Code Coverage + + Code Coverage - - GitHub CI Status + + GitHub CI Status

-## Dart client SDK proposal +## Repository source and client SDK beta -This repository also contains the design proposal for a separate, pure-Dart -OpenFeature client SDK intended for Dart VM, Dart web, and Flutter consumers. -The client SDK is not implemented or published yet. The existing server SDK -remains independently versioned and published. +This server package now lives at +`packages/openfeature_dart_server_sdk` in the source repository. Pub.dev +dependencies and `package:openfeature_dart_server_sdk/...` imports are +unchanged. Git dependencies that previously resolved the package from the +repository root must add: -- Read the [client SDK architecture](https://github.com/open-feature/dart-server-sdk/blob/main/doc/client-sdk-architecture.md). +```yaml +path: packages/openfeature_dart_server_sdk +``` + +The same repository also contains a separate pure-Dart client SDK beta for +Dart VM, Dart web, and Flutter consumers. The two packages remain independently +versioned and published. + +- See the + [client package](https://github.com/open-feature/dart-sdk/tree/main/packages/openfeature_dart_client_sdk). +- Read the + [client SDK architecture](https://github.com/open-feature/dart-sdk/blob/main/doc/client-sdk-architecture.md). - Review the - [client SDK conformance matrix](https://github.com/open-feature/dart-server-sdk/blob/main/doc/client-sdk-conformance-matrix.md). -- Follow [issue #117](https://github.com/open-feature/dart-server-sdk/issues/117) + [client SDK conformance matrix](https://github.com/open-feature/dart-sdk/blob/main/doc/client-sdk-conformance-matrix.md). +- Read the + [client beta release procedure](https://github.com/open-feature/dart-sdk/blob/main/doc/client-sdk-release.md). +- Follow [issue #117](https://github.com/open-feature/dart-sdk/issues/117) for implementation progress. ## Quick start @@ -68,7 +82,7 @@ Dart language version: [3.12.2](https://dart.dev/get-dart/archive) ```yaml dependencies: - openfeature_dart_server_sdk: ^0.0.23 + openfeature_dart_server_sdk: ^0.0.24 ``` ### Then run @@ -142,9 +156,9 @@ for the complete API documentation. ### Providers [Providers](/docs/reference/concepts/provider) are an -abstraction between a flag management system and the OpenFeature SDK. Look -[here](//ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5BallTechnologies%5D%5B0%5D=Dart) -for a complete list of available providers. If the provider you need does not +abstraction between a flag management system and the OpenFeature SDK. See the +[available providers](//ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5BallTechnologies%5D%5B0%5D=Dart) +for a complete list. If the provider you need does not exist yet, see [Develop a provider](#develop-a-provider). ```dart @@ -196,9 +210,9 @@ final result = await client.getBooleanFlag( ### Hooks [Hooks](/docs/reference/concepts/hooks) allow custom -logic to be added at well-defined points of the flag evaluation life-cycle. Look -[here](/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Dart) -for a complete list of available hooks. +logic to be added at well-defined points of the flag evaluation life-cycle. See +the [available hooks](/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Dart) +for a complete list. Once you have added a hook dependency, it can be registered at the global or client level. diff --git a/src/datasets/sdks/dart-client.ts b/src/datasets/sdks/dart-client.ts new file mode 100644 index 000000000..4f9a66c9c --- /dev/null +++ b/src/datasets/sdks/dart-client.ts @@ -0,0 +1,14 @@ +import { SDK } from '.'; + +export const DartClient: SDK = { + name: 'Dart', + category: 'Client', + description: 'OpenFeature static-context Dart client SDK for Dart and Flutter applications (beta).', + repo: 'dart-sdk', + folder: '/packages/openfeature_dart_client_sdk', + logoKey: 'dart-no-fill.svg', + technology: 'Dart', + href: '/docs/reference/sdks/client/dart', + // The beta has not completed conformance; do not imply a stable support matrix. + includeInSupportMatrix: false, +}; diff --git a/src/datasets/sdks/dart.ts b/src/datasets/sdks/dart.ts index 8f79a54ae..5e4757101 100644 --- a/src/datasets/sdks/dart.ts +++ b/src/datasets/sdks/dart.ts @@ -3,7 +3,8 @@ import { SDK } from '.'; export const Dart: SDK = { name: 'Dart', category: 'Server', - repo: 'dart-server-sdk', + repo: 'dart-sdk', + folder: '/packages/openfeature_dart_server_sdk', logoKey: 'dart-no-fill.svg', technology: 'Dart', href: '/docs/reference/sdks/server/dart', diff --git a/src/datasets/sdks/index.ts b/src/datasets/sdks/index.ts index 09005c116..a2bbbb49c 100644 --- a/src/datasets/sdks/index.ts +++ b/src/datasets/sdks/index.ts @@ -17,6 +17,7 @@ import { Cpp } from './cpp'; import { NextjsFlagsSDK } from './nextjs-flags-sdk'; import { SveltekitFlagsSDK } from './sveltekit-flags-sdk'; import { Dart } from './dart'; +import { DartClient } from './dart-client'; export const SDKS = [ Java, Nodejs, @@ -32,6 +33,7 @@ export const SDKS = [ Ruby, Angular, Dart, + DartClient, Rust, Cpp, NextjsFlagsSDK, diff --git a/src/datasets/sdks/sdk-compatibility.json b/src/datasets/sdks/sdk-compatibility.json index e158ec2a3..b84e05371 100644 --- a/src/datasets/sdks/sdk-compatibility.json +++ b/src/datasets/sdks/sdk-compatibility.json @@ -592,8 +592,8 @@ "path": "/docs/reference/sdks/server/dart", "category": "Server", "release": { - "href": "https://github.com/open-feature/dart-server-sdk/releases/tag/v0.0.23", - "version": "0.0.23", + "href": "https://github.com/open-feature/dart-sdk/releases/tag/v0.0.24", + "version": "0.0.24", "stable": false }, "spec": {