Contents

stanfordspezi/spezifoundation

This source file is part of the Stanford Spezi open-source project

Components

The SpeziFoundation package consists of 2 targets: SpeziFoundation and SpeziLocalization.

SpeziFoundation

The SpeziFoundation target provides general-purpose functionality that is shared by the other Spezi modules and available to apps built with Spezi:

| Area | What it provides | Documentation | | --- | --- | --- | | Shared Repository | A type-safe key-value store (ValueRepository, SendableValueRepository) whose keys are KnowledgeSource types, scoped to a RepositoryAnchor. Modules use it to exchange values without knowing about each other. | Shared Repository | | Local Preferences | @LocalPreference and LocalPreferencesStore: a type-safe, namespaced alternative to AppStorage and UserDefaults, including support for migrations. | Local Preferences | | Concurrency | AsyncSemaphore, withManagedTaskQueue, ManagedAsynchronousAccess, RWLock, cancelable child tasks, and withTimeout. | Concurrency | | Data Structures | OrderedArray, an always-sorted array with binary-search lookups, and Version, an implementation of Semantic Versioning 2.0.0. | OrderedArray, Version | | Collection Algorithms | Binary search, Set-producing map variants, sorting with heterogeneous SortComparators, and safe indexing. | Collection Algorithms | | Compression | Zstandard and zlib compression behind a common CompressionAlgorithm protocol, with typed errors. | Compression | | Markdown | MarkdownDocument: front-matter metadata parsing and extraction of custom elements (e.g., signature fields) from Markdown input. | MarkdownDocument | | Calendar and Time Zone | Calendar helpers for component-based date ranges and distances, and DST transition lookups on TimeZone. | Calendar | | Logging | A Logger type that maps to os.Logger on Apple platforms and to swift-log elsewhere, so the same code works on Linux. | Logger | | Other | Result builders for arrays and sets, TopLevelEncoder/TopLevelDecoder protocols, DataDescriptor for masked byte matching, Objective-C exception catching, and a testing SPI. | SpeziFoundation |

SpeziLocalization

The SpeziLocalization target adds localization utilities on top of Foundation:

  • Bundle extensions for looking up strings across multiple tables and for explicit languages, with language-tag fallback (e.g., en-GB to en);
  • LocalizedFileResource and LocalizedFileResolution for selecting the best-matching localized variant of a file (e.g., Welcome+de-DE.md) for a locale, regardless of where the files are stored;
  • LocalizationKey and LocalizationsDictionary for keying values by language and region, with fuzzy matching on lookup.

SpeziFoundation in the Spezi Ecosystem

Most Spezi modules build on SpeziFoundation. Some examples of how its components are used:

  • Spezi stores the values that modules provide and collect in a shared repository (SpeziStorage is a ValueRepository<SpeziAnchor>), and uses AsyncSemaphore, withTimeout, and cancelable child tasks to coordinate remote notification registration and the lifecycle of service modules.
  • SpeziAccount models account details as a SendableValueRepository: every AccountKey (user id, email address, etc.) is a KnowledgeSource anchored to AccountAnchor, which lets other packages define additional account keys.
  • SpeziScheduler stores task and outcome metadata in shared repositories, and uses AsyncSemaphore when scheduling notifications.
  • SpeziHealthKit keeps query results in OrderedArrays, runs bulk exports through withManagedTaskQueue, guards caches with RWLock and RecursiveRWLock, and wraps HealthKit calls that can raise Objective-C exceptions in catchingNSException.
  • SpeziBluetooth bridges CoreBluetooth's delegate callbacks into async/await with ManagedAsynchronousAccess, and uses RWLock, AsyncSemaphore, withTimeout, and DataDescriptor for device discovery.
  • SpeziLLM limits concurrent inference jobs with AsyncSemaphore and protects its queue state with RWLock.
  • SpeziViews renders MarkdownDocuments in its MarkdownView and re-exports SpeziLocalization; SpeziConsent builds its consent documents on MarkdownDocument.
  • SpeziStudy resolves the localized files of a study bundle with LocalizedFileResource and LocalizationKey.

Installation

The project can be added to your Xcode project or Swift Package using the Swift Package Manager.

Xcode: For an Xcode project, follow the instructions on adding package dependencies to your app.

Swift Package: You can follow the Swift Package Manager documentation about defining dependencies to add this project as a dependency to your Swift Package.

Contributing

Contributions to this project are welcome. Please make sure to read the contribution guidelines and the contributor covenant code of conduct first.

Testing on Linux

You can test SpeziFoundation on Linux using Docker. To do this, run the following command:

docker build -t spezi-foundation .

This will build the container and run the tests.

License

This project is licensed under the MIT License. See Licenses for more information.

[Spezi Footer] [Spezi Footer]

Package Metadata

Repository: stanfordspezi/spezifoundation

Default branch: main

README: README.md