Skip to content

About

An advanced MacOS/iOS Foundation extension library (collision-free)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

CI Platform Release License

BEFoundation

BEFoundation is an Objective-C framework that extends Apple's Foundation with utilities for notifications, runtime manipulation, number and data handling, image processing, data structures, file and path monitoring, security-scoped bookmarks, caching, and more. It is cross-platform (macOS and iOS) and ships as a Universal binary (arm64 + x86_64).


📖 Documentation

For full documentation, see the BEFoundation Documentation or the Documentation Index.


📦 Installation

Swift Package Manager

.package(url: "https://github.com/belisoful/BEFoundation.git", from: "1.2.0")

or add it in Xcode via File ▸ Add Package Dependencies….

CocoaPods

pod 'BEFoundation'

Binary

Download an artifact below and drop it into your target.


📥 Framework Library Downloads

The .xcframework is the recommended download: it carries macOS and iOS (device + simulator) in one binary, so a single artifact drops into any target. The plain .framework builds are macOS-only.


🔧 Features

📣 Notifications

  • mutableUserInfo for NSNotification
  • NSPriorityNotification: Notifications with explicit priority
  • NSPriorityNotificationCenter: Dispatches notifications in priority order linked to NSNotificationCenter

🔤 Character Sets

🖥️ Cross-Platform UI (iOS & macOS)

  • BEPlatformTypes: compile-time aliases (BEColor, BEImage, BEFont, BEView) that resolve to the right AppKit/UIKit class per platform, so the same source builds on both
  • BEColor+BExtension: hex-string colors (#RGB/#RGBA/#RRGGBB/#RRGGBBAA) and appearance-aware dynamic colors
  • BEColor+BEWebColor: the 141 CSS/SVG color keywords as constants, web-prefixed properties, and name lookups
  • BEView+BExtension: Auto Layout helpers: pin to superview/view, center, and size constraints
  • BEImage+BExtension: CGImage/CIImage round-trips, PNG/JPEG export, pixel size, and aspect-aware resize (fit/fill)
  • BEDotView: a status-indicator dot view (3D radial-gradient or flat), a port of Prado's TDot
  • NSPasteboard+BExtension (macOS): one-call typed read/write for strings, URLs, and images

🎞️ Image & Metal Helpers

  • BEMetalHelper: Metal helper utilities for converting MTLTextures to a BEImage (NSImage/UIImage), and grey data to XRGB
  • CIImage+BExtension: overlay images with alpha, render text

🧠 Runtime & Object Management

  • BEMutable: Mutable and Collection classes have their own protocols for distinction
  • NSObject+DynamicMethods: Runtime extensions to add selectors implemented by blocks to specific objects and classes
  • NSObject+Macroable: Laravel-inspired macro system for attaching block-based methods to classes and individual instances at runtime, built on top of NSObject+DynamicMethods
  • BEObjectRegistry: Global object registry with weak references to track object lifetimes
  • BESingleton: Singleton pattern macro

📚 Data Structures

  • BEStackExtensions: Array-based Stack and Queue (pushObject:, popObject, shift)
  • BEPriorityExtensions: Priority ordering extensions for NSArray and NSOrderedSet
  • FxTime: Immutable object to encapsulate CMTime and methods; FxMutableTime adds read-write components and in-place arithmetic

📡 File & Path Monitoring

  • BEPathWatcher: Path watcher class to observe file system changes

💾 Networking, Data & Storage

  • NSURL+Data: create and read data:-scheme URLs
  • BEWebData: read a resource through one interface, whether it is a data: URL, an http(s) download, or a local file
  • NSData+URLDownload: download remote data in memory or to a temporary file
  • BEFileCache: a two-tier cache, an NSCache memory tier over a durable on-disk tier indexed for O(1) cold start, with count/cost limits, NSDiscardableContent awareness, crash-safe reconciliation at launch, a score-driven eviction policy (last-access recency, retentionCost, and an evictionBalance dial between age and value density), and caller-defined entry file naming (fileNameBlock)
  • BESecurityScopedURLManager: create, resolve, and manage the access lifecycle of security-scoped bookmarks

🧮 Encoding, Numbers, and Dates

🧪 Predicate Logic

  • BEPredicateRule: Evaluation system that can accept, reject, or remain neutral based on predicate evaluation

🧩 Foundation Extensions

  • NSObject+DynamicMethods: Dynamic protocol conformance implemented by objects and classes
  • Extensions for:
    • NSDictionary+BExtension: numeric subscripts, object conversion, mapping, swapping, adding, and merging
    • NSMutableDictionary: numeric subscripts, filtering, swap, and recursive and nonrecursive adding and merging
    • NSArray+BExtension: mapping, and conversion
    • NSMutableArray: removeFirstElement, insertElementsOfArray:atIndex:, and filtering
    • NSSet+BExtension: conversion, and mapping
    • NSMutableSet: filtering
    • NSOrderedSet+BExtension: conversion, and mapping
    • NSMutableOrderedSet: conversion, removeFirstElement/removeLastElement, and filtering
    • NSString+BExtension: stringValue returns the receiver itself, aligning with NSNumber and other plist data types
    • NSMutableString: deleteAtIndex

🧪 Unit Testing

BEFoundation ships unit tests for all major components, using XCTest, covering behavior, edge cases, runtime behaviors, and error conditions. The suite runs parallelized across test workers. Continuous integration runs it on macOS (arm64), the macOS x86_64 slice, and the iOS Simulator, plus an AddressSanitizer pass, a DocC catalog build, xcodebuild analyze, pod lib lint, a SwiftPM build, a category-collision check, and builds under the newest Xcode 26 and under Xcode 27. In v1.1, coverage was extended to NSObject+Macroable (67 tests covering BEMacroMeta, class macros, object macros, invocation, isolation, and subclass inheritance).


📦 Integration

Framework Integration

  1. Download the BEFoundation.framework ZIP file for your project.
  2. Unzip the file.
  3. Include the BEFoundation.framework in your Project Target under the General Tab and "Framework and Libraries" section.
  4. Under the "Embed" dropdown select "Embed & Sign" or "Embed Without Signing".
  5. Import the Headers you'd like to use.

Manual Integration

  1. Clone or download this repository.
  2. Add the BEFoundation source folder to your Xcode project.
  3. Link against required frameworks: Foundation, CoreImage, Metal, etc.
  4. Ensure ARC is enabled (where applicable).

✍️ About the Author

Author

BEFoundation was initially conceived and engineered by belisoful@icloud.com to resolve the lack of [NSString stringValue] and implementing a selector for an object (and instances) with a block. These requirements came about in working with Apple's FxPlug API in developing an advanced framework around it. The FxPlug buttons require an object method be implemented per button which is not directly possible in Objective C. The buttons need to be parameterized for an FxPlug framework.

Other projects


Change Log

New in 1.2.0

  • Behavior change: the deployment minimums rise to macOS 12.0 and iOS 15.0 (from 11.0 and 14.0). Xcode 27 accepts nothing lower, and the project builds without overrides again. Update platforms in your package manifest or podspec if you pinned the old floor.

  • Release binaries are attached to each GitHub Release only; the Framework Release folders are no longer committed.

  • Fix: NSObject+Macroable and NSObject+DynamicMethods no longer deadlock when a macro is registered while another thread dispatches on the same class; cross-class lookups take the owning class's lock, dispatch validates the invocation signature, and re-registering an instance protocol with a different class reaches already-synced objects. See FIXES.md.

  • Fix: BESecurityScopedURLManager stops access on the NSURL instance that started it, so the sandbox extension is released; removeURLFromCatalog: ends the whole session. The new initWithStorageIdentifier: gives private instances their own persisted catalog.

  • Fix: NSPriorityNotificationCenter no longer serializes observer call-outs on the notification's userInfo. Behavior change: only defaultCenter bridges to NSNotificationCenter.defaultCenter; a center created with init is self-contained.

  • Fix: BEFileCache decodes payloads with secure coding. The new allowedClasses property admits custom NSSecureCoding classes; the payload's root class is recorded in the .meta sidecar.

  • Fix: NSNumber+Primes16b never returns 1 as a prime. NSDictionary+BExtension recursive merge and add descend into immutable nested dictionaries by default. NSNumber+BExtension follows IEEE 754 for floating divide-by-zero, returns NaN on integer overflow, and raises on a nil operand.

  • Fix: BEDotView applies its defaults on the initWithCoder: path, accepts #RGB shorthand, rejects malformed hex, and keeps explicit color overrides across a depth change. BEWindowController survives -close when its manager is the sole owner.

  • Fix: NSURL+Data is the single data-URL parser; BEWebData reads from it, so both APIs agree on case-insensitive and quoted parameters, whitespace in base64, and the default charset. +charsetFromMediaType: applies the same rules to an HTTP Content-Type. BEWebData frees a no-copy buffer through its deallocator.

  • Fix: BEColor webColorNamed: resolves the seven CSS grey spellings; colorWithHexString: rejects a doubled prefix such as #0x1234. FxTime and BECharacterSet fail a malformed secure-coded archive instead of decoding zeros. BEPredicateRule factories return instancetype and a nil predicate raises.

  • Behavior change (Swift): BECharacterSet, BEObjectRegistry, and BEUniversalObjectRegistry declare init nonnull, so Swift imports init() in place of init?().

  • Fix: BEObjectRegistry re-keying an object's UUID from a same-salt registry keeps the other registry's entry. BESecurityScopedURLManager fast enumeration works across calls. BEPathWatcher closes the descriptor and returns NO when its dispatch source cannot be created. NSNotification+ExtraProperties declares identifier as copy, matching its setter. NSData+URLDownload clamps the Content-Length allocation hint to 16 MB. BEDotView setters are safe under MRC and the class releases its ivars in dealloc.

  • BESecurityScopedURLManagerTests now runs on iOS.

  • NSMutableNumber is re-vendored from upstream v1.3.1, which compiles without warnings on Xcode 27.

  • The podspec license now reads Public Domain, matching LICENSE.

New in 1.1.1

  • Fix: NSPriorityNotificationCenter no longer crashes on notifications whose object is a non-object pointer. SceneKit posts such notifications through CFNotificationCenterPostNotification; the object is now read unretained, and super-center notifications reach queued observers unchanged. See FIXES.md.

New in 1.1

Cross-Platform (iOS & macOS)

  • The framework now builds and is unit-tested on both iOS and macOS. BEPlatformTypes provides compile-time aliases (BEColor, BEImage, BEFont, BEView) that resolve to the right AppKit/UIKit class per platform.
  • Distributed as a multi-platform BEFoundation.xcframework (macOS, iOS device, iOS simulator) alongside the macOS-only .framework builds.
  • Installable through Swift Package Manager and CocoaPods. Public headers moved to Sources/BEFoundation/include/BEFoundation/, so #import <BEFoundation/Foo.h> resolves the same way for SwiftPM, CocoaPods, and the built framework.
  • BEColor+BEWebColor: the 141 CSS/SVG color keywords as BEWebColorName… constants and web-prefixed class properties, with case-insensitive name lookup and exact reverse lookup.
  • BEDotView: a cross-platform status-indicator dot (3D or flat), a Core Graphics port of Prado's TDot.
  • BEColor+BExtension: hex-string colors and appearance-aware dynamic colors.
  • BEView+BExtension: Auto Layout convenience constraints (pin, center, size).
  • BEImage+BExtension: CGImage/CIImage round-trips, PNG/JPEG export, pixel size, and aspect-aware resizing.
  • Behavior change: the BEImage+BExtension round-trip and data members are renamed to representation-style names: CGImageRepresentation, CIImageRepresentation, imageFromCGImage:, imageFromCIImage:, pngRepresentation, jpegRepresentationWithCompressionQuality:. Apple frameworks attach same-named category methods to NSImage at runtime (PencilKit adds a private +[NSImage imageWithCGImage:] and -CGImage), and which duplicate wins is undefined, so the 1.0 UIImage-parity spellings were unsafe. pixelSize and the resizedTo… members keep their names. The round-trip members are also available on iOS now, and the factories return nil for NULL/nil input on both platforms.
  • NSPasteboard+BExtension (macOS): typed read/write for strings, URLs, and images.

Foundation & Networking

  • NSNotification+ExtraProperties adds tag and identifier if the notification object has such properties or are set in the NSNotification
  • NSString (CharacterCounter) category for counting characters of a NSString.
  • NSURL+Data: categories for creating and reading "data" scheme NSURL.
  • BEWebData: for decoding a "data" scheme within NSURL, download "http/s" files, or read file system files.
  • NSData+URLDownload: for easy download of internet data via in-memory or temporary file.
  • BEFileCache: persistent two-tier (memory + disk) caching with count/cost limits, crash-safe reconciliation at launch, a configurable score-driven eviction policy (retentionCost + evictionBalance), and caller-defined entry file naming (fileNameBlock).
  • BESecurityScopedURLManager: security-scoped bookmark lifecycle management.
  • NSDateFormatterRFC2822: fixed-format RFC 2822 (Internet Message Format) date formatter for email-style dates.
  • NSObject+Macroable: Macro system for attaching block-based methods to a class (available on all instances) or to a specific object instance at runtime, built on NSObject+DynamicMethods.
  • FxTime is now immutable and thread-safe. The new FxMutableTime subclass carries the read-write components and in-place arithmetic; code that mutated an FxTime must now use FxMutableTime. -copy returns an immutable FxTime; -mutableCopy returns an FxMutableTime.
  • Behavior change: FxTime -compare:/-compareTime: now follow the Cocoa NSComparisonResult convention. The result sign is inverted versus 1.0; code that compensated for the old inversion must drop the workaround.
  • Behavior change: NSCoder+AtIndex.h no longer imports <simd/simd.h> (it was unused). Clients that relied on the transitive include through the umbrella header must import <simd/simd.h> themselves.

Behavior change: category methods renamed off Apple's private selectors

Apple attaches private categories to Foundation classes at runtime, and when a BEFoundation category defined the same selector the runtime picked a winner by image load order. The build emits no diagnostic; a collision surfaces as an intermittent test failure. Every colliding selector is renamed; the behavior is unchanged.

1.0 1.1 Collided with
-[NSMutableArray push:], -pop -pushObject:, -popObject OSAnalytics (its push: returns nil, breaking chaining)
-[NSMutableOrderedSet push:], -pop -pushObject:, -popObject — (renamed with the array pair for symmetry)
-removeFirstObject, -removeLastObject -removeFirstElement, -removeLastElement CoreFoundation
-[NSMutableArray insertObjects:atIndex:] -insertElementsOfArray:atIndex: ScreenReaderCore
setSet:, setOrderedSet:, setArray: setters be_setSet:, be_setOrderedSet:, be_setArray: CoreFoundation
isMutable (class and instance) hasMutability Foundation's private per-instance predicate on every NSCharacterSet

The set, orderedSet, and array properties keep their names; only the setter selectors changed, so dot syntax (array.set = value) is unaffected. Scripts/check-category-collisions.sh now fails the build if any category selector reappears on an Apple class; it runs in CI.

Behavior change: queued priority-notification observers

An observer registered with an NSOperationQueue now receives a plain NSPriorityNotification it may retain indefinitely. Previously it received a pooled object that was recycled the moment the handler returned, so a retained notification's name, object, and userInfo went nil and were later overwritten by an unrelated post. NSPooledPriorityNotification is removed; it was also measurably slower than plain allocation under concurrent posting.

Behavior change: NSMutableNumber is a genuine NSNumber subclass

NSMutableNumber now inherits from NSNumber. isKindOfClass: reports NSNumber, equality with a plain NSNumber is symmetric, CFNumberRef bridging works, and inherited API such as decimalValue returns a value instead of raising. Vendored from the standalone NSMutableNumber v1.3.0.

AppKit

  • BEPathControl: an NSPathControl that displays paths relative to a sub-directory.
  • BETabView: a drop-in NSTabView replacement that supports hidden tabs.
  • BEWindowController: a drop-in NSWindowController replacement with parent/child window-controller relationships and a windowDidLoad notification.
  • BEWindowControllerManager: an application singleton that tracks window controllers and closes children when a parent closes.

About

An advanced MacOS/iOS Foundation extension library (collision-free)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages