Contents

ryanfrancesconi/spfk-utils

A Swift utility library providing UI definitions and Foundation/CoreGraphics conveniences for macOS and iOS development.

Requirements

  • Platforms: macOS 13+, iOS 16+
  • Swift: 6.2+

Modules

Definitions

  • Rescale — Linear interpolation and mapping between numeric domains and ranges.
  • Counter — Simple incrementing counter with reset support.
  • ProgressTracker / ChunkedProgressTracker — Track completion progress as a normalized value, with optional chunked progress for parallel operations.
  • URLProperties — Structured metadata container for URL-associated properties.
  • HardwareInfo — System hardware queries (chip, chip name, memory, hardware UUID).
  • StereoState — Enumeration of stereo routing states (normal, flipped, mono).
  • ByteCount — Binary size constants and human-readable file-size formatting.
  • DictionaryMergeScheme — How two dictionaries combine: preserve, replace, or combine.
  • CSVBuilder — RFC 4180 CSV text from a header row and a per-row value provider.
  • GroupByTagDirectory — Resolves an output directory by appending subdirectories derived from tag values, splitting on / so a value can name a nested path, or, with nestsOnSlash: false, keeping each value one folder.
  • Email — Composing a mail message.

Concurrency

  • BatchFileConverter — Runs a per-file conversion over a batch of FileConversionWork: bounded concurrency, every output name settled before any file starts (two outputs sharing a path, compared case-insensitively where the volume is, are numbered apart, and an output never takes another item's input), each file's failure kept to that file, and results in input order.
  • batchMap — Bounded-concurrency map over a collection. For CPU-bound work set the batch size near the core count, since a task holds a thread while it runs; for suspending work it is a resource knob rather than a throughput one, because a suspended task holds no thread.

Caching

  • ImageDataStore / ImageDataStoreAccess / CachedImageType — A disk cache for decoded images, and the narrow protocol a data layer exposes it through.
  • ShardedDirectory — A 2-hex-character prefix scheme (256 shards) laid out as <root>/<key[0..<2]>/<key><suffix>, so a large library does not pay flat-directory enumeration costs.

Timers

  • DisplayLinkTimer / LegacyDisplayLinkTimer — Screen-refresh-synced timing for playhead and transport updates, behind the TimerModel protocol with TimerState.

Outline and table state

  • OutlineNode / OutlineNodeCollection / NodeIdentifier — The sidebar tree's node model and its stable identifier.
  • OutlineState — Expansion state, persisted.
  • OutlineEditOperation — One edit to that tree.
  • NavigationHistory — Back/forward through sidebar selections.
  • TableColumnState — One column's title, stable identifier, width and visibility, saved independently of AppKit's autosave. The identifier is always the matching key; old saves predating the title/identifier split fall back to using the title as the identifier.
  • TableColumnPreset / TableSortState / SortValue — A named column layout, and how a table is sorted.
  • PasteboardCopyable — What a type does to put itself on the pasteboard.

UI

  • SPFKSchemeColor — The two neutral grays used as default arguments by SPFKSymbol.tinted() and NSImageConvertible.stateImage(). It lives here because non-UI packages use it as a default argument.
  • SPFKSymbol — SF Symbol definitions with tinting and state images. Here for the same reason.
  • AppearanceObserver — Observe system appearance (light/dark mode) changes via Combine.
  • StateImage — Associate images with on/off/disabled control states.
  • FirstResponder — Utilities for managing first responder status in AppKit.

Extensions

Categorized extensions across Foundation, AppKit and CoreGraphics:

| Category | Highlights | |---|---| | Foundation | URL (file and content-type icons), UUID (zero constants), NumberFormatter | | AppKit | NSView (Auto Layout constraint helpers), NSImage (resizing, tinting), NSWindow (title bar height, modal state), NSEdgeInsets (convenience inits) | | CoreGraphics | CGRect (square fitting), CGSize (equality init), CGColor (hex conversion) | | XML | AEXMLDocument (load from a path, URL or string), AEXMLElement (child and attribute lookup, writing to a URL) |

Entropy

Embedded EntropyString library for generating cryptographically random identifiers with configurable character sets and entropy levels (small, medium, large, session, token).

Dependencies

| Package | Description | |---|---| | spfk-audio-base | Shared audio type definitions (test target only) | | spfk-filesystem | File system utilities, directory observation, Finder tags | | spfk-image | Encoding, decoding and fingerprints for the image data store | | AEXML | XML parsing and generation | | spfk-base | Common extensions and logging (test target only) | | spfk-testing | Test infrastructure (test target only) |

About

Spongefork is the personal software projects of musician and developer Ryan Francesconi. Dedicated to creative sound manipulation, his first application, Spongefork, was released in 1999 for macOS 8. From 2026, Spongefork returns as his software container for more musical experimentation. In addition to software releases, open source components can be found on his GitHub page.

Package Metadata

Repository: ryanfrancesconi/spfk-utils

Default branch: main

README: README.md