feat: initial interface library

Author: nilslice

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+
+name: CI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test-example:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Install Zig
+        uses: goto-bus-stop/setup-zig@v2
+        with:
+          version: 0.13.0
+
+      - name: Check Zig Version
+        run: zig version
+          
+      - name: Run tests
+        run: zig build test

.gitignore

@@ -0,0 +1,2 @@
+zig-cache
+zig-out

LICENSE

@@ -0,0 +1,18 @@
+Copyright 2024 Steve Manuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,131 @@
+# Zig Interfaces & Validation
+
+A compile-time interface checker for Zig that enables interface-based design
+with comprehensive type checking and detailed error reporting.
+
+## Features
+
+This library provides a way to define and verify interfaces in Zig at compile
+time. It supports:
+
+- Type-safe interface definitions with detailed error reporting
+- Interface embedding (composition)
+- Complex type validation including structs, enums, arrays, and slices
+- Comprehensive compile-time error messages with helpful hints
+- Flexible error union compatibility with `anyerror`
+
+## Install
+
+```
+TODO
+```
+
+## Usage
+
+1. Define an interface with required method signatures:
+
+```zig
+const Repository = Interface(.{
+    .create = fn(anytype, User) anyerror!u32,
+    .findById = fn(anytype, u32) anyerror!?User,
+    .update = fn(anytype, User) anyerror!void,
+    .delete = fn(anytype, u32) anyerror!void,
+}, null);
+```
+
+2. Implement the interface methods in your type:
+
+```zig
+const InMemoryRepository = struct {
+    allocator: std.mem.Allocator,
+    users: std.AutoHashMap(u32, User),
+    next_id: u32,
+
+    pub fn create(self: *InMemoryRepository, user: User) !u32 {
+        var new_user = user;
+        new_user.id = self.next_id;
+        try self.users.put(self.next_id, new_user);
+        self.next_id += 1;
+        return new_user.id;
+    }
+
+    // ... other Repository methods
+};
+```
+
+3. Verify the implementation at compile time:
+
+```zig
+// In functions that accept interface implementations:
+fn createUser(repo: anytype, name: []const u8, email: []const u8) !User {
+    comptime Repository.satisfiedBy(@TypeOf(repo));
+    // ... rest of implementation
+}
+
+// Or verify directly:
+comptime Repository.satisfiedBy(InMemoryRepository);
+```
+
+## Interface Embedding
+
+Interfaces can embed other interfaces to combine their requirements:
+
+```zig
+const Logger = Interface(.{
+    .log = fn(anytype, []const u8) void,
+    .getLogLevel = fn(anytype) u8,
+}, null);
+
+const Metrics = Interface(.{
+    .increment = fn(anytype, []const u8) void,
+    .getValue = fn(anytype, []const u8) u64,
+}, .{ Logger });  // Embeds Logger interface
+
+// Now implements both Metrics and Logger methods
+const MonitoredRepository = Interface(.{
+    .create = fn(anytype, User) anyerror!u32,
+    .findById = fn(anytype, u32) anyerror!?User,
+}, .{ Metrics });
+```
+
+> Note: you can embed arbitrarily many interfaces!
+
+## Error Reporting
+
+The library provides detailed compile-time errors when implementations don't
+match:
+
+```zig
+// Wrong parameter type ([]u8 vs []const u8)
+const BadImpl = struct {
+    pub fn writeAll(self: @This(), data: []u8) !void {
+        _ = self;
+        _ = data;
+    }
+};
+
+// Results in compile error:
+// error: Method 'writeAll' parameter 1 has incorrect type:
+//    └─ Expected: []const u8
+//    └─ Got: []u8
+//       └─ Hint: Consider making the parameter type const
+```
+
+## Complex Types
+
+The interface checker supports complex types including:
+
+```zig
+const ComplexTypes = Interface(.{
+    .process = fn(
+        anytype,
+        struct { config: Config, points: []const DataPoint },
+        enum { ready, processing, error },
+        []const struct {
+            timestamp: i64,
+            data: ?[]const DataPoint,
+            status: Status,
+        }
+    ) anyerror!?ProcessingResult,
+}, null);
+```

build.zig

@@ -0,0 +1,55 @@
+const std = @import("std");
+
+// Although this function looks imperative, note that its job is to
+// declaratively construct a build graph that will be executed by an external
+// runner.
+pub fn build(b: *std.Build) void {
+    // Standard target options allows the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
+    const target = b.standardTargetOptions(.{});
+
+    // Standard optimization options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
+    // set a preferred release mode, allowing the user to decide how to optimize.
+    const optimize = b.standardOptimizeOption(.{});
+
+    const interface_lib = b.addModule("interface", .{
+        .root_source_file = b.path("src/interface.zig"),
+    });
+
+    // Creates a step for unit testing. This only builds the test executable
+    // but does not run it.
+    const simple_unit_tests = b.addTest(.{
+        .root_source_file = b.path("test/simple.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    simple_unit_tests.root_module.addImport("interface", interface_lib);
+    const run_simple_unit_tests = b.addRunArtifact(simple_unit_tests);
+
+    const complex_unit_tests = b.addTest(.{
+        .root_source_file = b.path("test/complex.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    complex_unit_tests.root_module.addImport("interface", interface_lib);
+    const run_complex_unit_tests = b.addRunArtifact(complex_unit_tests);
+
+    const embedded_unit_tests = b.addTest(.{
+        .root_source_file = b.path("test/embedded.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    embedded_unit_tests.root_module.addImport("interface", interface_lib);
+    const run_embedded_unit_tests = b.addRunArtifact(embedded_unit_tests);
+
+    // Similar to creating the run step earlier, this exposes a `test` step to
+    // the `zig build --help` menu, providing a way for the user to request
+    // running the unit tests.
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_simple_unit_tests.step);
+    test_step.dependOn(&run_complex_unit_tests.step);
+    test_step.dependOn(&run_embedded_unit_tests.step);
+}

build.zig.zon

@@ -0,0 +1,67 @@
+.{
+    .name = "interface",
+    // This is a [Semantic Version](https://semver.org/).
+    // In a future version of Zig it will be used for package deduplication.
+    .version = "0.0.1",
+
+    // This field is optional.
+    // This is currently advisory only; Zig does not yet do anything
+    // with this value.
+    //.minimum_zig_version = "0.11.0",
+
+    // This field is optional.
+    // Each dependency must either provide a `url` and `hash`, or a `path`.
+    // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
+    // Once all dependencies are fetched, `zig build` no longer requires
+    // internet connectivity.
+    .dependencies = .{
+        // See `zig fetch --save <url>` for a command-line interface for adding dependencies.
+        //.example = .{
+        //    // When updating this field to a new URL, be sure to delete the corresponding
+        //    // `hash`, otherwise you are communicating that you expect to find the old hash at
+        //    // the new URL.
+        //    .url = "https://example.com/foo.tar.gz",
+        //
+        //    // This is computed from the file contents of the directory of files that is
+        //    // obtained after fetching `url` and applying the inclusion rules given by
+        //    // `paths`.
+        //    //
+        //    // This field is the source of truth; packages do not come from a `url`; they
+        //    // come from a `hash`. `url` is just one of many possible mirrors for how to
+        //    // obtain a package matching this `hash`.
+        //    //
+        //    // Uses the [multihash](https://multiformats.io/multihash/) format.
+        //    .hash = "...",
+        //
+        //    // When this is provided, the package is found in a directory relative to the
+        //    // build root. In this case the package's hash is irrelevant and therefore not
+        //    // computed. This field and `url` are mutually exclusive.
+        //    .path = "foo",
+
+        //    // When this is set to `true`, a package is declared to be lazily
+        //    // fetched. This makes the dependency only get fetched if it is
+        //    // actually used.
+        //    .lazy = false,
+        //},
+    },
+
+    // Specifies the set of files and directories that are included in this package.
+    // Only files and directories listed here are included in the `hash` that
+    // is computed for this package.
+    // Paths are relative to the build root. Use the empty string (`""`) to refer to
+    // the build root itself.
+    // A directory listed here means that all files within, recursively, are included.
+    .paths = .{
+        // This makes *all* files, recursively, included in this package. It is generally
+        // better to explicitly list the files and directories instead, to insure that
+        // fetching from tarballs, file system paths, and version control all result
+        // in the same contents hash.
+        "",
+        // For example...
+        //"build.zig",
+        //"build.zig.zon",
+        //"src",
+        //"LICENSE",
+        //"README.md",
+    },
+}