{"id":25080101,"url":"https://github.com/juyan/swift-filestore","last_synced_at":"2025-04-15T04:02:16.329Z","repository":{"id":168923801,"uuid":"644730430","full_name":"juyan/swift-filestore","owner":"juyan","description":"Lightweight key-value store with Structured Concurrency API","archived":false,"fork":false,"pushed_at":"2025-01-29T22:11:30.000Z","size":36,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T09:01:47.263Z","etag":null,"topics":["database","ios","key-value-store","macos","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/juyan.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}},"created_at":"2023-05-24T06:23:12.000Z","updated_at":"2025-01-29T22:11:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"c97e6d08-f244-42a1-bf1b-21a4c19e70f0","html_url":"https://github.com/juyan/swift-filestore","commit_stats":null,"previous_names":["juyan/swift-filestore"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juyan%2Fswift-filestore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juyan%2Fswift-filestore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juyan%2Fswift-filestore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juyan%2Fswift-filestore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juyan","download_url":"https://codeload.github.com/juyan/swift-filestore/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003951,"owners_count":21196793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["database","ios","key-value-store","macos","swift"],"created_at":"2025-02-07T03:17:45.663Z","updated_at":"2025-04-15T04:02:16.293Z","avatar_url":"https://github.com/juyan.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swift-filestore\nLightweight key-value store with Structured Concurrency API. \n\n![MIT License](https://img.shields.io/github/license/juyan/swift-filestore)\n![Package Releases](https://img.shields.io/github/v/release/juyan/swift-filestore)\n![Build Results](https://img.shields.io/github/actions/workflow/status/juyan/swift-filestore/.github/workflows/swift.yml?branch=main)\n![Swift Version](https://img.shields.io/badge/swift-5.5-critical)\n![Supported Platforms](https://img.shields.io/badge/platform-iOS%2014%20%7C%20macOS%2012-lightgrey)\n\n\n## Why swift-filestore? \n\nIf your app is built with Swift Concurrency and is in need for a lightweight key-value storage solution, `swift-filestore` should be a good fit.\n\nIt is a key-value persistence solution which provides CRUD operation and change stream APIs under Swift's Structured Concurrency(`async/await`, `AsyncSequence`).\nUnder the hood it simply serializes each object into a separate file, no databases or caches solutions are involved. This keeps your app lean and stable.\n\n## Quick Start\n\nObtain an instance by calling `FileObjectStore.create()`. The method simply create a root directory under app's `Application Support` directory.\nIn rare cases where it fails to create the directory, you can choose to fallback to a in-memory implementation of `ObjectStore`, or can handle it in your own way.\n\n```swift\nfunc createWithFallback() -\u003e ObjectStore {\n  do {\n    return try FileObjectStore.create()\n  } catch {\n    return MemoryObjectStore()\n  }\n}\n```\n\n`swift-filestore` does not require developers to create new struct/classes for your data model. For example, to use JSON serialization, just have your existing model conform to `JSONDataRepresentable`.\n\n```swift\n\nstruct MyModel: Codable, JSONDataRepresentable {\n    let id: String\n    let value: String\n}\n\nlet model = MyModel()\ntry await objectStore.write(key: model.id, namespace: \"MyModels\", object: model)\n```\n\n## Object Change Stream\n\n`swift-filestore` offers an object change subscription API via Swift Concurrency.\n\n```swift\nfor try await model in await objectStore.observe(key: id, namespace: \"MyModels\", objectType: MyModel.self) {\n    // process the newly emitted model object\n}\n```\n\n## Custom serialization/deserialization\n\nIf you are looking for non-json serializations, you can define your custom serialization/deserialization protocol as below:\n\n```swift\n\nprotocol BinaryDataRepresentable: DataRepresentable {}\n\nextension BinaryDataRepresentable {\n\n  public func serialize() throws -\u003e Data {\n    // your custom serialization goes here...\n  }\n  \n  public static func from(data: Data) throws -\u003e Self {\n    // your custom deseriazation goes here...\n  }\n}\n\nstruct MyModel: BinaryDataRepresentable {\n    let id: String\n    let value: String\n}\n```\n\n## PersistenceLog\n\n`swift-filestore` offers an immutable logging component named `PersistenceLog`. It allows developer to store records on the disk and flush them at the right time. It can be used as an alternative to in-memory logging, which may risk data loss because app can be terminated at any time by user or the system.\n\n\nBelow code demonstrates how to use `PersistenceLog` to store and send in-app analytic events:\n```swift\n//data model for the analytics log\nstruct AnalyticsEvent: Codable, JSONDataRepresentable {\n    let name: String\n    let metaData: String\n}\n\n//initialization\nlet log = try PersistenceLogImpl\u003cAnalyticsEvent\u003e(name: \"analytics-log\")\n\n//When new event is triggered\ntry await log.append(event1)\n\n//When it's time to flush and sent to remote server\nlet events = try await log.flush()\ntry await networkClient.sendAnalytics(events)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuyan%2Fswift-filestore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuyan%2Fswift-filestore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuyan%2Fswift-filestore/lists"}