add initial implementation

Author: atomicptr

.luacheckrc

@@ -0,0 +1,17 @@
+return {
+    read_globals = { "describe", "it" },
+
+    stds = {
+        busted = {
+            read_globals = {
+                "describe",
+                "it",
+                "before_each",
+                "after_each",
+                "assert",
+                "spy",
+            },
+        },
+    },
+    std = "_G+busted",
+}

.stylua.toml

@@ -0,0 +1,6 @@
+column_width = 120
+line_endings = "Unix"
+indent_type = "Spaces"
+indent_width = 4
+quote_style = "AutoPreferDouble"
+call_parentheses = "None"

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Christopher Kaster <[email protected]>
+
+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,64 @@
+# spec.lua
+
+spec.lua is a lightweight library for defining and validating data structures in Lua, inspired by Clojures `spec` system.
+
+It allows you to declaratively specify the shape and constraints of your data (e.g. tables, strings, numbers) and validate
+against those specs at runtime. This helps catch errors early, document your data contracts and make your code more robust.
+
+## Installation
+
+The recommended way to install `spec.lua` is to put the file inside your project as a vendored library
+
+## Example
+
+```lua
+local spec = require "spec"
+
+-- spec.lua provides built-in predicates for common types
+local is_string = spec.valid(spec.string, "Hello, World") -- true
+
+assert(spec.valid(spec.number, 1337))
+
+if spec.valid(spec.boolean, true) then
+    -- ...
+end
+
+-- create specs for table shapes
+local user_spec = spec.keys {
+    name = spec.string,
+    age = spec.number,
+}
+
+spec.valid(user_spec, { name = "Alice", age = 30}) -- valid
+spec.valid(user_spec, { name = "Bob" }) -- invalid, missing key
+spec.valid(user_spec, { name = "Charlie", age = "thirty" }) -- invalid, not a number
+
+-- or you can write your own predicates
+---@param my_type MyType
+---@return boolean
+function my_predicate(my_type)
+    return my_type:condition_is_valid()
+end
+
+spec.valid(my_predicate, instance_of_type) -- true if condition is valid
+
+-- some useful helper functions...
+
+-- conform returns the value if it conforms to the spec
+local alice = { name = "Alice", age = 30 }
+local bob = { name = "Bob" } -- invalid because it has no age...
+
+local user = spec.conform(user_spec, alice) -- returns alice if valid
+if user then
+    print(user.name) -- Alice
+end
+
+spec.conform(user_spec, bob) -- returns nil
+
+-- assert that the spec is valid otherwise throw an error
+spec.assert(spec.string, "Hello, World")
+```
+
+## License
+
+MIT

spec.lua

@@ -0,0 +1,122 @@
+-- This file is part of spec.lua
+--
+-- Repository: https://github.com/atomicptr/spec.lua
+--
+-- License:
+--
+-- Copyright 2025 Christopher Kaster <[email protected]>
+--
+-- 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.
+
+local M = {}
+
+-- predicates
+
+---Tests if value is a string
+---@param value any
+---@return boolean
+function M.string(value)
+    return type(value) == "string"
+end
+
+---Tests if value is a number
+---@param value any
+---@return boolean
+function M.number(value)
+    return type(value) == "number"
+end
+
+---Tests if value is a boolean
+---@param value any
+---@return boolean
+function M.boolean(value)
+    return type(value) == "boolean"
+end
+
+---Tests if value is a table
+---@param value any
+---@return boolean
+function M.table(value)
+    return type(value) == "table"
+end
+
+---Tests if value is nil
+---@param value any
+---@return boolean
+function M.null(value)
+    return value == nil
+end
+
+---Tests if value exists
+---@param value any
+---@return boolean
+function M.some(value)
+    return value ~= nil
+end
+
+---Test if table matches a shape
+---@param spec_map table<string, fun(value: any): boolean>
+---@return fun(value: any): boolean
+function M.keys(spec_map)
+    return function(value)
+        if not M.table(value) then
+            return false
+        end
+
+        for key, sub_spec in pairs(spec_map) do
+            local val = value[key]
+
+            if val == nil or not (type(sub_spec) == "function" and sub_spec(val)) then
+                return false
+            end
+        end
+
+        return true
+    end
+end
+
+---Check if a value matches with the given spec
+---@param spec fun(value: any): boolean
+---@param value any
+---@return boolean
+function M.valid(spec, value)
+    if type(spec) ~= "function" then
+        error "Spec must be a function (e.g. spec.keys for tables)"
+    end
+
+    return spec(value)
+end
+
+---Returns value if it matches the spec, nil otherwise
+---@generic T
+---@param spec fun(value: any): boolean
+---@param value T
+---@return T|nil
+function M.conform(spec, value)
+    if M.valid(spec, value) then
+        return value
+    end
+
+    return nil
+end
+
+---Asserts that a spec is valid
+---@param spec any
+---@param value any
+function M.assert(spec, value)
+    assert(M.valid(spec, value))
+end
+
+return M