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 usually are not.

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.

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.