swift

name: swift description: Design, implement, and review Swift APIs and Apple-platform code. Use when working on .swift files, Swift types, Foundation or AVFoundation APIs, DispatchQueue, async/await, Task, actors, MainActor, thread-affine state, or Swift-backed React Native Nitro Module implementations.

Swift

Use this skill for Swift code that needs strong API boundaries, predictable threading, and idiomatic Apple-platform integration. When the code is part of a Nitro Module, pair this with build-nitro-modules for generated specs, Promise mapping, and HybridObject constraints.

Workflow

1. Read the local Swift code, generated protocols, and surrounding API shape before editing.
2. Choose the public type model first: make invalid states unrepresentable where Swift can express them.
3. Choose one concurrency model for the feature before writing implementation code.
4. Keep synchronous properties and methods cheap, local, and nonblocking.
5. Make queue hops, hardware/session negotiation, I/O, and fallible async work explicit in the API.

Type-Safe API Design

• Represent state variants with types, not nullable clusters. Use protocols plus conforming structs/classes when variants share a public contract, or use enum with associated values when the set is closed and value-like.
• Keep related fields nonoptional on the same variant. If barcode and barcodeType are meaningful only together, put both on ScannedBarcode; do not make both optional on a generic scanned-data struct.
• Use optionals only for real domain absence inside one state, not for expressing which state the object is in.
• Prefer compile-time flow over caller-side probing. If callers need repeated if let chains to discover valid field combinations, the API shape is probably wrong.

// Avoid: the valid combinations are implicit and easy to misuse.
struct ScannedData {
  let position: Point
  let text: String?
  let barcode: String?
  let barcodeType: BarcodeType?
  let face: Rect?
}

// Prefer: each state exposes the fields that are valid for that state.
protocol ScannedData {
  var position: Point { get }
}

struct ScannedText: ScannedData {
  let position: Point
  let text: String
}

struct ScannedBarcode: ScannedData {
  let position: Point
  let barcode: String
  let barcodeType: BarcodeType
}

struct ScannedFace: ScannedData {
  let position: Point
  let face: Rect
}

Concurrency Model

• Choose Swift concurrency or DispatchQueue for a feature, not both as interleaved control flow.
• Keep quick, deterministic, local work synchronous. Do not introduce Task, DispatchQueue, or Promise plumbing for simple value construction, cached metadata, or pure transforms.
• Use Swift async/await, Task, and actors only when the full operation can be represented cleanly in Swift concurrency without queue escape hatches.
• Use a private owned serial DispatchQueue when Apple APIs, delegates, callbacks, C++ bridges, JS runtimes, or Nitro thread boundaries already revolve around queues, or when heavier native work must not block the caller.
• Avoid DispatchQueue.main unless the platform API requires the main thread, such as UIKit/AppKit/VisionKit presentation or view mutation. Keep main-thread blocks small and move parsing, conversion, I/O, session negotiation, and CPU work to an owned queue or async API.
• Treat repeated Task, DispatchQueue, actor, or thread hops as an architecture smell. A component should either own the queue/actor it works on, or cross into that owner once at the public async boundary or native callback boundary.
• If a workflow bounces between main, background, JS, and native queues in multiple nested places, stop and redesign the object/lifecycle/API. Excessive hops hide latency, make ordering harder to reason about, and create future performance problems.
• Do not fix races or readiness bugs with DispatchQueue.asyncAfter, Task.sleep, Thread.sleep, timers, extra queue hops, or calling the same method twice. Fix the owner queue, lifecycle state, completion callback, delegate event, or async API boundary instead. Retry only for external nondeterminism such as hardware, OS services, remote services, or network, and keep retries bounded, cancellable, and idempotent.
• Do not use Task { @MainActor in ... } as a generic main-thread hop from a nonisolated or Nitro-generated entry point. It creates unstructured Swift concurrency. Use it only when the operation is otherwise Swift-concurrency based and benefits from async/await, task cancellation, or actor isolation end to end.
• For UIKit, AppKit, VisionKit, and other main-thread callback/delegate APIs, prefer a direct DispatchQueue.main.async boundary or an async public method that owns the hop. Direct DispatchQueue.main.async is understood by Swift's actor checker for @MainActor calls; generic queue wrappers such as Promise.parallel(.main) usually are not.
• If a callback can return on an arbitrary queue, normalize it to the chosen owner queue once, close to the callback source, instead of scattering nested Task { @MainActor } or DispatchQueue.main.async hops through the workflow.
• Do not force MainActor.assumeIsolated, Thread.isMainThread branches, or queue .sync calls to make a Swift-concurrency design compile. That is a signal to choose a queue-based design or change the API boundary.
• Do not call DispatchQueue.sync, DispatchQueue.main.sync, or equivalent synchronous queue hops. Treat them as bugs, especially in property getters and setters.
• Use DispatchQueue.async or a Nitro Promise method for queue-bound work that callers must wait for.
• Treat locks as a last-resort synchronization primitive, not a default safety wrapper. Before adding NSLock, identify the concrete shared mutable values, the threads/queues that can access them concurrently, and why ownership by MainActor, a serial queue, a Nitro runtime/thread, or immutable snapshots is not enough.
• Swift Array and Dictionary mutations are not thread-safe. If listener add/remove can race with native delegate emission, either serialize every access on one owner queue/thread, or use a tiny lock only to mutate and snapshot the listener registry.
• Never hold a lock while invoking callbacks, calling into JS/Nitro, or calling unknown user code. Snapshot listeners under the lock, unlock, then call them. A listener removed during an in-flight emission may receive that current event; that is acceptable cleanup semantics and does not justify heavier locking.

Properties and Threading

• Use properties only for cheap observed state that can be read or written immediately and safely.
• Do not hide a thread hop, hardware/session query, lock wait, permission check, allocation, or fallible native operation behind a property.
• If a value can only be observed from a specific queue, prefer an event/listener emitted from that queue.
• If a caller truly needs a one-shot read from another queue, expose an async getter method instead of a property.
• In Nitro Modules, represent queue-bound reads and writes as Promise<T> methods, usually with Promise.parallel(queue).

// Avoid: synchronous queue hop hidden in a getter.
var status: SessionStatus {
  queue.sync { session.status }
}

// Prefer: make the async boundary explicit.
func getStatus() throws -> Promise<SessionStatus> {
  return Promise.parallel(queue) {
    return self.session.status
  }
}

Swift Style

• Make classes final by default unless subclassing is part of the design.
• Prefer Swift-native types such as String, Array, Dictionary, structs, protocols, and Foundation value types. Avoid Objective-C bridge types unless an Apple API requires them.
• Use guard to validate input and state early. Throw specific errors for user-reachable failures.
• Treat a filename as a scope contract. HybridDataScanner.swift should implement HybridDataScanner; it should not also contain extensions, conversions, UIViewController helpers, delegates, or framework adapters.
• Keep one top-level implementation type per file. Do not put secondary structs, classes, enums, protocols, option adapters, coordinators, delegates, or helper types below the primary type. If a helper deserves a type, it deserves its own file.
• Keep one focused extension/conversion per file. Do not collect multiple extensions in one utility file. Put reusable extensions in named files such as Extensions/UIViewController+topPresentedViewController.swift, Extensions/CGPoint+Point.swift, or Extensions/Barcode+toScannedCode.swift with internal or package visibility where appropriate.
• Never put Swift extensions inside Hybrid* implementation files or other primary implementation files, even when the extension is private, tiny, or only used by that file. Put every extension in a separate named Type+operation.swift extension/converter file so code splitting, maintainability, and future diffs stay clean.
• Split delegates, framework adapters, converters, native protocols, and helper state into separate files instead of adding them below the main type.
• Extract native preflight checks and platform boilerplate out of Hybrid* factories and implementation methods. Permission/status switches, Bundle.main.object(forInfoDictionaryKey:) checks, hardware capability checks, Info.plist validation, and similar setup guards belong in focused helper/extension files such as AVCaptureDevice+CameraAuthorization.swift or Bundle+CameraUsageDescription.swift; the factory call site should stay one or two lines.
• Keep Hybrid*Factory.swift as orchestration only: resolve generated options, call preflight helpers, create/start the native session, and return/reject the Promise. Do not define session/coordinator/delegate classes, Native*Options adapters, presenter traversal helpers, scanner configuration builders, barcode mappings, permission switches, or Info.plist checks in the factory file.
• If a Hybrid* method grows a switch over Apple authorization/status, a multi-line guard for platform setup, view-controller lookup logic, DataScannerViewController configuration, or conversion loops, extract it before continuing. The caller should read as a short sequence of named operations, not as the implementation of each operation.
• Do not create broad Utils.swift files for these helpers. Name the file after the platform type or domain check and keep each helper focused on one check or conversion.
• Use line count as a review signal: files below roughly 300 lines are usually fine only after the one-type-per-file and no-helpers-in-factory rules are satisfied. Size caused by extensions, conversions, helper types, or platform glue is a design issue.
• Prefer inline shorthand for unambiguous single-expression closures: targetFormats.flatMap { $0.toVNBarcodeFormat() }, not a multi-line flatMap { format in format.toVNBarcodeFormat() }. Do not use $0 when a surrounding or nested closure already uses shorthand arguments; name parameters in nested closures or when clarity needs it.
• Put conversions on the element type, not on arrays, when the conversion only reads one element. The element method may still return multiple values; compose callers with map, flatMap, reduce, or Set(...).
• Do not put domain conversions on broad/common receivers such as Int, String, Double, Any, CGPoint, or CGRect unless the conversion is genuinely about that type. Prefer the domain type direction, such as BarcodeFormat.from(format:) or BarcodeFormat(nativeFormat:), over Int.toBarcodeFormat().
• Add Array or Collection extensions only when the collection has real domain behavior, such as validation across elements, deduplication, ordering, batching, caching, nonempty checks, or error aggregation. If the receiver is a concrete [SomeDomainType] and the body mostly saves one map, keep that map in caller code.
• Break meaningful conversions into named intermediate values instead of long inline expressions.

Nitro Notes

• Use Promise.parallel(queue) for DispatchQueue-based work such as AVFoundation session operations.
• Use Promise.async only when wrapping Swift async/await or Task-native APIs end to end.
• Avoid manually creating or passing around Promise<T> instances. Prefer Promise.parallel, Promise.async, Promise.resolved, and Promise.rejected; use a manual Promise only for real native completion/delegate/callback bridges and keep it in the smallest scope with exactly-once completion.
• Do not mix Promise.async with queue .sync calls or actor escape hatches.
• Generated HybridObject properties are synchronous entry points. Redesign them as methods or listeners if they need queue affinity.