swift-primitives/swift-serializer-primitives

Quick Start

A serializer appends a value's machine-readable representation to a buffer. The leaf conformer is Serializer.Witness, a closure-backed serializer; combinators compose serializers into larger ones, and a @Serializer.Builder var body lets a domain type declare its format declaratively.

import Serializer_Primitive

// A leaf serializer: write an unsigned byte, infallibly.
let octet = Serializer.Witness<UInt8, [UInt8], Never> { value, buffer in
    buffer.append(value)
}

// Failure == Never means no `try` at the call site; returns a fresh buffer.
let bytes: [UInt8] = octet.serialize(255)   // [255]

// Compose declaratively: a dotted-quad serializer built from a `var body`.
struct DottedQuad: Serializer.`Protocol` {
    typealias Output = (UInt8, UInt8, UInt8, UInt8)
    typealias Buffer = [UInt8]
    typealias Failure = Never

    var body: some Serializer.`Protocol`<Output, [UInt8], Never> {
        Serializer.Witness<Output, [UInt8], Never> { quad, buffer in
            buffer.append(contentsOf: "\(quad.0).\(quad.1).\(quad.2).\(quad.3)".utf8)
        }
    }
}

let address: [UInt8] = DottedQuad().serialize((192, 168, 0, 1))   // "192.168.0.1" as UTF-8

Transform inputs with map, validate with filter, and recover the failure type through the typed-throws channel:

import Serializer_Primitive
import Serializer_Map_Primitives

let octet = Serializer.Witness<UInt8, [UInt8], Never> { value, buffer in
    buffer.append(value)
}

// Contravariantly map a String to the byte serializer's UInt8 input.
let lengthByte = octet.map { (text: String) -> UInt8 in UInt8(text.utf8.count) }
let encoded: [UInt8] = lengthByte.serialize("hello")   // [5]

Installation

dependencies: [
    .package(url: "https://github.com/swift-primitives/swift-serializer-primitives.git", branch: "main")
]

.target(
    name: "App",
    dependencies: [
        .product(name: "Serializer Primitive", package: "swift-serializer-primitives"),
    ]
)

Requires Swift 6.3.1 and macOS 26 / iOS 26 / tvOS 26 / watchOS 26 / visionOS 26 (or the matching Linux / Windows toolchain).

Architecture

The namespace target carries the protocol and the closure-backed witness; each combinator is its own target so consumers depend only on what they use. The umbrella re-exports everything.

| Product | When to import | |---------|----------------| | Serializer Primitive | The Serializer.Protocol, Serializer.Witness / Serializer.Pure, Serializable, and Serializer.Builder. The minimal core. | | Serializer Map Primitives | Contravariant input transforms — map(:) and throwing tryMap(:). | | Serializer Filter Primitives | Predicate validation — filter(_:). | | Serializer Sequence Primitives | Sequential composition (Sequence.Two / Sequence.Three) over one shared value. | | Serializer Many Primitives | Repetition with count bounds, and separator-delimited repetition. | | Serializer Optional Primitives | Compile-time-optional (Optional) and runtime-optional (Optionally) serializers. | | Serializer Literal Primitives | Fixed byte-sequence emission for delimiters and keywords. | | Serializer Always Primitives | The identity serializer that writes nothing. | | Serializer Fail Primitives | The serializer that always throws a chosen error. | | Serializer Lazy Primitives | Deferred construction for recursive formats. | | Serializer Trace Primitives | Debug tracing around any serializer. | | Serializer Tagged Primitives | Serializable for Tagged, lifting the underlying value's serializer. | | Serializer Primitives Standard Library Integration | Serializable for Swift.Optional. | | Serializer Primitives | Umbrella re-exporting every product above. |

Foundation-free; depends only on other primitives packages.

Platform Support

| Platform | Status | |----------|--------| | macOS 26 | Full support | | Linux | Full support | | Windows | Full support | | iOS / tvOS / watchOS / visionOS | Supported | | Swift Embedded | Supported |

Community

License

Apache 2.0. See LICENSE.md.

Package Metadata

Repository: swift-primitives/swift-serializer-primitives

Default branch: main

README: README.md