kts

Kind	ffi-zig
Capabilities	ffi
Categories	data-structures concurrency caching
Keywords	kts ets table cache concurrency in-memory

Kit Term Storage - fast, concurrent in-memory tables inspired by Erlang's ETS

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic usage example
`examples/snapshot.kit`	Example: snapshot
`kit.toml`	Package manifest with metadata and dependencies
`src/kts.kit`	KTS error type for typed error handling.
`tests/error-types.test.kit`	Tests for error-types
`tests/query-operations.test.kit`	Tests for query-operations
`tests/set-operations.test.kit`	Tests for set-operations
`tests/snapshot.test.kit`	Tests for snapshot
`tests/table-lifecycle.test.kit`	Tests for table-lifecycle
`zig/kit_ffi.zig`	Zig FFI module for kit ffi
`zig/kts.zig`	Zig FFI module for kts

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-kts.git

Usage

import Kit.KTS as KTS

main = fn(-env: Env) =>
  # Create a named set table
  users = KTS.new "users" :set[:named]

  # Insert records
  -ins = KTS.insert users {id: 1, name: "Alice", role: "admin"}
  KTS.insert-batch users [
    {id: 2, name: "Bob", role: "user"}, 
    {id: 3, name: "Carol", role: "admin"}
  ]

  # Lookup by key
  match KTS.lookup users 1
    | Some user -> println "Found: ${to-string user}"
    | None -> println "Not found"

  # Pattern matching query
  admins = KTS.pattern-match users {role: "admin"}
  println "Admins: ${to-string (length admins)}"

  # Save table to disk
  match KTS.save users "/tmp/users.json"
    | Ok _ -> println "Saved!"
    | Err e -> println "Save failed: ${KTSError.message e}"

  # Delete and restore from snapshot
  -del = KTS.delete-table users
  match KTS.load "/tmp/users.json"
    | Ok restored ->
      println "Restored ${to-string (KTS.size restored)} records"
      -d = KTS.delete-table restored
      no-op
    | Err e -> println "Load failed: ${KTSError.message e}"

main

API Overview

Table Management

Function	Signature	Description
`KTS.new`	`String -> Symbol -> List Symbol -> Ptr`	Create a table (`:set`, `:ordered-set`, `:bag`, `:duplicate-bag`)
`KTS.delete-table`	`Ptr -> Bool`	Delete a table and free resources
`KTS.whereis`	`String -> Option Ptr`	Look up a named table by name
`KTS.info`	`Ptr -> Record`	Get table metadata (name, type, size)
`KTS.rename`	`Ptr -> String -> Bool`	Rename a table

Insert Operations

Function	Signature	Description
`KTS.insert`	`Ptr -> a -> Bool`	Insert or overwrite a record
`KTS.insert-new`	`Ptr -> a -> Bool`	Insert only if key doesn't exist
`KTS.insert-batch`	`Ptr -> List a -> Bool`	Bulk insert multiple records

Lookup Operations

Function	Signature	Description
`KTS.lookup`	`Ptr -> a -> Option b`	Look up a record by key
`KTS.has-key?`	`Ptr -> a -> Bool`	Check if a key exists

Delete Operations

Function	Signature	Description
`KTS.delete`	`Ptr -> a -> Bool`	Delete a record by key
`KTS.delete-record`	`Ptr -> a -> Bool`	Delete a specific record (for bags)
`KTS.delete-all`	`Ptr -> Bool`	Delete all records from a table

Query Operations

Function	Signature	Description
`KTS.select`	`Ptr -> (a -> Bool) -> List a`	Select records matching a predicate
`KTS.select-limit`	`Ptr -> (a -> Bool) -> Int -> List a`	Select with a result limit
`KTS.fold`	`Ptr -> b -> (a -> b -> b) -> b`	Fold over all records
`KTS.pattern-match`	`Ptr -> a -> List b`	Match records by pattern (`:_` wildcard)
`KTS.to-list`	`Ptr -> List a`	Get all records as a list
`KTS.keys`	`Ptr -> List a`	Get all keys as a list

Utility Operations

Function	Signature	Description
`KTS.size`	`Ptr -> Int`	Get the number of records
`KTS.is-empty?`	`Ptr -> Bool`	Check if the table is empty
`KTS.memory`	`Ptr -> Int`	Get approximate memory usage in bytes

Snapshot Operations

Function	Signature	Description
`KTS.save`	`Ptr -> String -> Result Unit KTSError`	Save table to a JSON file
`KTS.load`	`String -> Result Ptr KTSError`	Load table from a JSON snapshot

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/snapshot.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic
kit build examples/snapshot.kit && ./snapshot

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/kts/, making it available for import as Kit.KTS in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`KTSError`

KTS error type for typed error handling.

Variants

TableCreateError {message}

TableNotFoundError {message}

InvalidKeyError {message}

TableClosedError {message}

`TableType`

Table type variants for different storage patterns. - Set: Unique keys, O(1) lookup (hash map) - OrderedSet: Unique keys, sorted, O(log n) lookup (balanced tree) - Bag: Duplicate keys allowed, unique values per key - DuplicateBag: Duplicate keys and values allowed

Variants

Set

OrderedSet

Bag

DuplicateBag

`TableOption`

Table options for configuring access and behavior. - :named - Table can be looked up by name via KTS.whereis - :public - Any process can read/write (default) - :protected - Any process can read, only owner can write - :private - Only owner can read/write

Variants

Named

Public

Protected

Private