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`	Kit Term Storage API
`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 values
`zig/kts.zig`	Zig FFI module for KTS

Dependencies

No Kit package dependencies.

KTS requires the ffi capability when running or building programs that import it.

Installation

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

Usage

import Kit.KTS as KTS
import Kit.KTS.{KTSError}

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

  # Insert records
  KTS.insert users {id: 1, name: "Alice", role: "admin", score: 95}
  KTS.insert users {id: 2, name: "Bob", role: "user", score: 82}
  KTS.insert-batch users [
    {id: 3, name: "Carol", role: "admin", score: 91}, 
    {id: 4, name: "Dave", role: "user", score: 74}
  ]

  println "Total users: ${to-string (KTS.size users)}"

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

  # Query by pattern
  admins = KTS.pattern-match users {role: "admin"}
  println "Admins found: ${to-string (length admins)}"

  # Work with named tables
  match KTS.whereis "users"
    | Some table-id -> println "Named table id: ${to-string table-id}"
    | None -> println "Named table not found"

  # Save a snapshot
  match KTS.save users "/tmp/kts-users.json"
    | Ok _ -> println "Saved users snapshot"
    | Err e -> println "Save failed: ${KTSError.message e}"

  # Clear records without deleting the table
  KTS.delete-all users
  println "Is empty? ${to-string (KTS.is-empty? users)}"

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi
kit run examples/snapshot.kit --allow=ffi

Compile examples to a native binary:

kit build examples/basic.kit --allow=ffi && ./basic
kit build examples/snapshot.kit --allow=ffi && ./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