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:
Bundleextensions for looking up strings across multiple tables and for explicit languages, with language-tag fallback (e.g.,en-GBtoen);LocalizedFileResourceandLocalizedFileResolutionfor 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;LocalizationKeyandLocalizationsDictionaryfor 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 (
SpeziStorageis aValueRepository<SpeziAnchor>), and usesAsyncSemaphore,withTimeout, and cancelable child tasks to coordinate remote notification registration and the lifecycle of service modules. - SpeziAccount models account details as a
SendableValueRepository: everyAccountKey(user id, email address, etc.) is aKnowledgeSourceanchored toAccountAnchor, which lets other packages define additional account keys. - SpeziScheduler stores task and outcome metadata in shared repositories, and uses
AsyncSemaphorewhen scheduling notifications. - SpeziHealthKit keeps query results in
OrderedArrays, runs bulk exports throughwithManagedTaskQueue, guards caches withRWLockandRecursiveRWLock, and wraps HealthKit calls that can raise Objective-C exceptions incatchingNSException. - SpeziBluetooth bridges CoreBluetooth's delegate callbacks into async/await with
ManagedAsynchronousAccess, and usesRWLock,AsyncSemaphore,withTimeout, andDataDescriptorfor device discovery. - SpeziLLM limits concurrent inference jobs with
AsyncSemaphoreand protects its queue state withRWLock. - SpeziViews renders
MarkdownDocuments in itsMarkdownViewand re-exports SpeziLocalization; SpeziConsent builds its consent documents onMarkdownDocument. - SpeziStudy resolves the localized files of a study bundle with
LocalizedFileResourceandLocalizationKey.
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