add zig 0.15+ patterns notes

synthesized from leaflet-search, find-bufo, zql, pollz

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/ziglang/README.md

···
+# zig 0.15+
+
+notes on zig 0.15+ patterns. pre-0.15 patterns are not covered here.
+
+sources: leaflet-search, find-bufo, zql, pollz (dec 2025 - jan 2026)
+
+---
+
+## build system
+
+### module imports (0.15+ pattern)
+
+```zig
+const exe = b.addExecutable(.{
+    .name = "myapp",
+    .root_module = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .imports = &.{
+            .{ .name = "websocket", .module = websocket.module("websocket") },
+            .{ .name = "zqlite", .module = zqlite.module("zqlite") },
+        },
+    }),
+});
+```
+
+### build.zig.zon
+
+```zig
+.{
+    .name = .my_project,
+    .version = "0.0.1",
+    .minimum_zig_version = "0.15.0",
+    .dependencies = .{
+        .websocket = .{
+            .url = "https://github.com/karlseguin/websocket.zig/archive/refs/heads/master.tar.gz",
+            .hash = "...",
+        },
+    },
+}
+```
+
+### library modules
+
+```zig
+const mod = b.addModule("zql", .{
+    .root_source_file = b.path("src/root.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+
+const tests = b.addTest(.{ .root_module = mod });
+```
+
+---
+
+## memory management
+
+### general purpose allocator (application lifetime)
+
+```zig
+var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+defer _ = gpa.deinit();
+const allocator = gpa.allocator();
+```
+
+### arena allocator (request-scoped)
+
+```zig
+fn handleRequest(request: *http.Server.Request) !void {
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+    const alloc = arena.allocator();
+    // all allocations freed when arena deinits
+}
+```
+
+### arraylist lifecycle
+
+```zig
+var list: std.ArrayList(u8) = .{};
+defer list.deinit(allocator);
+try list.appendSlice(allocator, data);
+```
+
+---
+
+## error handling
+
+### try with propagation
+
+```zig
+const result = try doSomething();  // propagates error
+```
+
+### catch with specific error handling
+
+```zig
+const n = tls_client.reader.stream(&w, .limited(len)) catch |err| {
+    if (err == error.EndOfStream) break :outer;
+    return error.Failed;
+};
+```
+
+### catch with default
+
+```zig
+const port = std.fmt.parseInt(u16, port_str, 10) catch 443;
+```
+
+### labeled blocks for fallback values
+
+```zig
+const count: i64 = blk: {
+    const row = db.conn.row("SELECT COUNT(*) FROM x", .{}) catch break :blk 0;
+    if (row) |r| {
+        defer r.deinit();
+        break :blk r.int(0);
+    }
+    break :blk 0;
+};
+```
+
+---
+
+## concurrency
+
+### thread pool
+
+```zig
+var pool: Thread.Pool = undefined;
+try pool.init(.{ .allocator = allocator, .n_jobs = 16 });
+defer pool.deinit();
+
+pool.spawn(handleConnection, .{conn}) catch |err| {
+    conn.stream.close();
+};
+```
+
+### mutex for shared state
+
+```zig
+pub var mutex: Thread.Mutex = .{};
+
+pub fn insert(data: []const u8) !void {
+    mutex.lock();
+    defer mutex.unlock();
+    // critical section
+}
+```
+
+### atomic values
+
+```zig
+posts_checked: std.atomic.Value(u64) = .init(0),
+
+// increment
+_ = self.posts_checked.fetchAdd(1, .monotonic);
+
+// read
+const count = self.posts_checked.load(.monotonic);
+```
+
+### background thread
+
+```zig
+const thread = try Thread.spawn(.{}, consumer, .{allocator});
+```
+
+### exponential backoff
+
+```zig
+var backoff: u64 = 1;
+const max_backoff: u64 = 60;
+
+while (true) {
+    connect() catch {};
+    posix.nanosleep(backoff, 0);
+    backoff = @min(backoff * 2, max_backoff);
+}
+```
+
+---
+
+## networking
+
+### tcp + tls (0.15 pattern)
+
+```zig
+const stream = net.tcpConnectToHost(allocator, host, 443) catch return error.Failed;
+defer stream.close();
+
+var arena = std.heap.ArenaAllocator.init(allocator);
+defer arena.deinit();
+const aa = arena.allocator();
+
+var ca_bundle: std.crypto.Certificate.Bundle = .{};
+ca_bundle.rescan(aa) catch return error.Failed;
+
+const buf_len = std.crypto.tls.max_ciphertext_record_len;
+const buf = aa.alloc(u8, buf_len * 4) catch return error.Failed;
+
+var stream_writer = stream.writer(buf.ptr[0..buf_len][0..buf_len]);
+var stream_reader = stream.reader(buf.ptr[buf_len .. 2 * buf_len][0..buf_len]);
+
+var tls_client = tls.Client.init(
+    stream_reader.interface(),
+    &stream_writer.interface,
+    .{
+        .ca = .{ .bundle = ca_bundle },
+        .host = .{ .explicit = host },
+        .read_buffer = buf.ptr[2 * buf_len .. 3 * buf_len][0..buf_len],
+        .write_buffer = buf.ptr[3 * buf_len .. 4 * buf_len][0..buf_len],
+    },
+) catch return error.Failed;
+```
+
+### tls read loop (must loop until data)
+
+```zig
+outer: while (total_read < response_buf.len) {
+    var w: std.Io.Writer = .fixed(response_buf[total_read..]);
+    while (true) {
+        const n = tls_client.reader.stream(&w, .limited(remaining)) catch break :outer;
+        if (n != 0) {
+            total_read += n;
+            break;
+        }
+    }
+}
+```
+
+### http server
+
+```zig
+var read_buffer: [8192]u8 = undefined;
+var write_buffer: [8192]u8 = undefined;
+
+var reader = conn.stream.reader(&read_buffer);
+var writer = conn.stream.writer(&write_buffer);
+
+var server = http.Server.init(reader.interface(), &writer.interface);
+
+while (true) {
+    var request = server.receiveHead() catch return;
+    handleRequest(&request) catch return;
+    if (!request.head.keep_alive) return;
+}
+```
+
+### socket timeouts
+
+```zig
+const timeout = std.mem.toBytes(posix.timeval{ .sec = 30, .usec = 0 });
+try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.RCVTIMEO, &timeout);
+try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.SNDTIMEO, &timeout);
+```
+
+---
+
+## json
+
+### parsing
+
+```zig
+const parsed = json.parseFromSlice(json.Value, allocator, data, .{}) catch return;
+defer parsed.deinit();
+
+const root = parsed.value.object;
+const val = root.get("key") orelse return;
+if (val != .string) return;
+const s = val.string;
+```
+
+### formatting output
+
+```zig
+try writer.print("{f}", .{json.fmt(value, .{})});
+```
+
+---
+
+## comptime
+
+### type-returning functions
+
+```zig
+pub fn Query(comptime sql: []const u8) type {
+    comptime {
+        const parsed = parser.parse(sql);
+        return struct {
+            pub const raw = sql;
+            pub const positional = parsed.positional[0..parsed.positional_len];
+        };
+    }
+}
+```
+
+### inline for (unrolled at comptime)
+
+```zig
+inline for (params) |p| {
+    if (!hasField(fields, p)) {
+        @compileError("missing param :" ++ p);
+    }
+}
+```
+
+### reflection
+
+```zig
+const fields = @typeInfo(Args).@"struct".fields;
+inline for (fields) |f| {
+    @field(result, f.name) = @field(args, f.name);
+}
+```
+
+### compile-time validation
+
+```zig
+@compileError("missing param :" ++ p ++ " in args struct")
+```
+
+### branch quota for complex parsing
+
+```zig
+@setEvalBranchQuota(sql.len * 100);
+```
+
+---
+
+## strings
+
+### splitting
+
+```zig
+var parts = mem.splitScalar(u8, data, '/');
+const first = parts.next() orelse return error.Invalid;
+```
+
+### prefix/suffix checks
+
+```zig
+if (mem.startsWith(u8, target, "/api/")) { }
+if (mem.endsWith(u8, id, "#atproto")) { }
+```
+
+### searching
+
+```zig
+if (mem.indexOf(u8, response, "\r\n\r\n")) |idx| {
+    const body = response[idx + 4 ..];
+}
+```
+
+### url decoding
+
+```zig
+const buf = try alloc.dupe(u8, encoded);
+const decoded = std.Uri.percentDecodeInPlace(buf);
+```
+
+---
+
+## common dependencies
+
+- **websocket.zig** (karlseguin) - websocket client with tls
+- **zqlite.zig** (karlseguin) - sqlite wrapper
+
+---
+
+## idioms
+
+### defer for cleanup
+
+```zig
+var arena = std.heap.ArenaAllocator.init(allocator);
+defer arena.deinit();
+```
+
+### errdefer for error cleanup
+
+```zig
+const resource = try allocate();
+errdefer deallocate(resource);
+// if error after this, resource is cleaned up
+```
+
+### optional access with type check
+
+```zig
+if (obj.get("key")) |val| {
+    if (val == .string) {
+        use(val.string);
+    }
+}
+```
+
+### environment variables with defaults
+
+```zig
+const host = std.posix.getenv("HOST") orelse "localhost";
+```
+
+### multi-line strings
+
+```zig
+const sql =
+    \\CREATE TABLE IF NOT EXISTS polls (
+    \\  uri TEXT PRIMARY KEY,
+    \\  text TEXT NOT NULL
+    \\)
+;
+```