{"id":46646855,"url":"https://github.com/lynnswap/observationbridge","last_synced_at":"2026-05-27T03:09:30.543Z","repository":{"id":339739539,"uuid":"1163194374","full_name":"lynnswap/ObservationBridge","owner":"lynnswap","description":"ObservationBridge is an integration layer that provides a consistent API for Swift Observations.","archived":false,"fork":false,"pushed_at":"2026-04-23T08:15:26.000Z","size":185,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T10:18:16.578Z","etag":null,"topics":["ios","macos","observation","observations","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lynnswap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-21T08:39:06.000Z","updated_at":"2026-04-23T08:13:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lynnswap/ObservationBridge","commit_stats":null,"previous_names":["lynnswap/observationscompat","lynnswap/observationbridge"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/lynnswap/ObservationBridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lynnswap%2FObservationBridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lynnswap%2FObservationBridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lynnswap%2FObservationBridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lynnswap%2FObservationBridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lynnswap","download_url":"https://codeload.github.com/lynnswap/ObservationBridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lynnswap%2FObservationBridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32494275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios","macos","observation","observations","swift"],"created_at":"2026-03-08T05:02:06.017Z","updated_at":"2026-05-27T03:09:30.532Z","avatar_url":"https://github.com/lynnswap.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ObservationBridge\n\nObservationBridge helps non-SwiftUI code consume `@Observable` state changes.\n\nIt provides:\n\n- owner-bound callbacks through `ObservationScope`\n- `AsyncSequence` streams through `ObservationBridge` / `makeObservationBridgeStream`\n\n## Requirements\n\n- Swift 6.2\n- iOS 18+\n- macOS 15+\n\n## Owner-Bound Observation\n\nUse `ObservationScope` as the lifecycle owner for UIKit/AppKit views, view\ncontrollers, cells, or other non-SwiftUI objects that render observable state.\n\n```swift\nimport ObservationBridge\n\nlet observations = ObservationScope()\n\nobservations.observe(model) { event, model in\n    if event.kind == .initial {\n        installViewsIfNeeded()\n    }\n\n    titleLabel.text = model.title\n    countLabel.text = \"\\(model.count)\"\n    saveButton.isEnabled = model.canSave\n}\n```\n\nThe callback body is the tracking body. Every observable property read from\n`model` inside the callback becomes part of the observation.\n\n### Events\n\n`ObservationEvent.kind` describes why the callback is running:\n\n- `.initial`: the first tracking pass\n- `.didSet`: a later pass after observed state changed\n\n`ObservationOptions` controls which later events are delivered:\n\n```swift\nobservations.observe(model, options: .didSet) { event, model in\n    render(model)\n}\n\nobservations.observe(model, options: []) { event, model in\n    renderOnce(model)\n}\n```\n\n`[]` delivers only `.initial`. `.didSet` delivers `.initial` plus subsequent\nchange-triggered passes. `.willSet` is intentionally unavailable until the\nnative Swift 6.4 backend can provide accurate about-to-change timing.\n\nCall `event.cancel()` to stop the current observation, or `cancelAll()` to tear\ndown every observation owned by the scope:\n\n```swift\nobservations.cancelAll()\n```\n\n`ObservationEvent.matches(_:)` is intentionally unavailable before the Swift 6.4\nnative backend because the changed key path is not exposed by the older public\nObservation API.\n\n## AsyncSequence Style\n\nUse `ObservationBridge` when async backpressure, iteration, or rate limiting is\nthe natural fit.\n\n```swift\nlet stream = ObservationBridge {\n    model.count\n}\n\nfor await value in stream {\n    print(value)\n}\n```\n\n`makeObservationBridgeStream` is equivalent:\n\n```swift\nlet stream = makeObservationBridgeStream {\n    model.count\n}\n```\n\n### Stream Options\n\n`ObservationStreamOptions` configures backend selection and rate limiting for\nstream observations.\n\n```swift\nlet debounce = ObservationDebounce(interval: .milliseconds(250))\n\nlet stream = ObservationBridge(\n    options: .rateLimit(.debounce(debounce))\n) {\n    model.count\n}\n```\n\nAvailable stream configuration:\n\n- `ObservationStreamOptions(rateLimit:backend:)`\n- `.rateLimit(ObservationRateLimit)`\n- `.legacyBackend` on iOS 26.0+ / macOS 26.0+\n- `ObservationDebounce(interval:tolerance:mode:)`\n- `ObservationThrottle(interval:mode:)`\n\nBackend notes:\n\n- automatic stream observations use the legacy `withObservationTracking` loop on Swift 6.2/6.3\n- native `withContinuousObservation` integration is reserved for Swift 6.4+\n- `.legacyBackend` keeps forcing the legacy backend after native support is added\n- non-`Sendable` stream values use the legacy backend\n\n## Testing\n\nThe APIs in this section are for tests. Production UIKit/AppKit rendering code\nshould usually keep using the `Void` callback form shown above:\n\n```swift\nobservations.observe(model) { _, model in\n    titleLabel.text = model.title\n}\n```\n\n### Owner-Bound UI Rendering Timing\n\nUse `ObservationDelivery` when the behavior under test belongs to a native UI\nowner: a view controller, view, cell, toolbar item owner, or AppKit controller\nthat renders observable state into existing UI objects. Keep the production\ncallback in the normal `Void` form, and attach a sampler that reads a small\n`Sendable` UI-facing snapshot after each delivery.\n\n```swift\nstruct RenderedState: Sendable, Equatable {\n    var primaryText: String?\n    var actionEnabled: Bool\n}\n\nlet delivery = observations.observe(model) { _, model in\n    renderNativeViews(from: model)\n}\n\nlet renderedStates = await delivery.values {\n    RenderedState(\n        primaryText: primaryTextForTesting,\n        actionEnabled: actionButton.isEnabled\n    )\n}\n\ntriggerModelChange()\n\n#expect(await renderedStates.waitUntilValue(\n    RenderedState(primaryText: expectedText, actionEnabled: true)\n))\n```\n\nSample rendered facts such as label text, enabled state, selected identifiers,\nrow counts, accessibility values, presentation state, or native object identity.\nDo not install a second observation just to wait for the raw model value; that\ndoes not prove the production callback has rendered. Pure model state changes\nshould usually be tested directly against the model, without going through\n`ObservationBridge`.\n\n`ObservationDelivery.cancel()` cancels the backing observation. `values { ... }`\nreturns an `ObservedValues\u003cValue\u003e` recorder for one sampled value stream.\nAwaiting `values { ... }` registers the sampler and, when the observation has\nalready delivered once, samples the current rendered state before returning.\n`ObservedValues\u003cValue\u003e` is limited to `Value: Sendable` because values can cross\nan async boundary while tests wait. It exposes `latestValue`, `snapshot()`,\n`waitUntilValue(_:timeout:)`, `waitUntil(timeout:_:)`, `cancel()`, and\n`isActive`. Keep the `ObservedValues` instance alive for as long as the test\nexpects updates; call `cancel()` when the test no longer needs that sampled\nstream.\n\nThe `timeout` on `ObservedValues` wait methods is only a test guard. It does not\ninject a clock into owner-bound observation delivery.\n\n### Stream Rate-Limit Timing\n\nFor stream debounce or throttle tests, inject a `Clock` into the stream API\ninstead:\n\n```swift\nlet debounce = ObservationDebounce(interval: .milliseconds(250))\n\nlet stream = makeObservationBridgeStream(\n    options: .rateLimit(.debounce(debounce)),\n    clock: testClock\n) {\n    model.title\n}\n```\n\nThat `clock:` controls stream rate-limit timing only. It is separate from\n`ObservedValues` timeouts and from the owner-bound `observe` callback pipeline.\n\n## Migration\n\n### v0.9.0\n\nThese notes apply when upgrading from `v0.8.x` or earlier to `v0.9.0`.\n\n- Owner-bound observation now starts from `ObservationScope`. Replace\n  `model.observe(...).store(in: observations)` with\n  `observations.observe(model) { event, model in ... }`.\n- The callback body is now the tracking body. Read every observed property from\n  `model` inside the callback instead of passing key paths to `observe`.\n- `ObservationRegistration` and `.store(in:)` have been removed without a\n  compatibility shim.\n\n```swift\nmodel.observe(\\.count) { value in\n    countLabel.text = \"\\(value)\"\n}\n.store(in: observations)\n```\n\nAfter:\n\n```swift\nobservations.observe(model) { _, model in\n    countLabel.text = \"\\(model.count)\"\n}\n```\n\n- `observeTask` has been removed without a compatibility shim. For simple\n  fire-and-forget work, start a `Task` from `observe` after copying the values\n  you need.\n\n```swift\nobservations.observe(model) { _, model in\n    let count = model.count\n    Task {\n        await analytics.trackCount(count)\n    }\n}\n```\n\n- If ordering, cancellation, or backpressure matter, use `ObservationBridge` or\n  `makeObservationBridgeStream` instead of recreating the old `observeTask`\n  queueing behavior.\n- `id:`, `ObservationScope.update(_:)`, and `ObservationScope.cancel(id:)` have\n  been removed. Use one `ObservationScope` per lifecycle owner and call\n  `cancelAll()` before rebinding a dynamic set of observations.\n- `ObservationOptions` is now an owner-bound event option set. Use `.didSet` for\n  initial + subsequent callbacks, or `[]` for initial-only callbacks.\n- `ObservationEvent.matches(_:)` is not exposed on Swift 6.3 and earlier. It is\n  reserved for the Swift 6.4 native backend where stdlib exposes matching.\n- Stream rate-limit and backend settings moved from `ObservationOptions` to\n  `ObservationStreamOptions`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flynnswap%2Fobservationbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flynnswap%2Fobservationbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flynnswap%2Fobservationbridge/lists"}