query

Fluent SQL query builder for Kit

Files

Dependencies

No Kit package dependencies.

Installation

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

Usage

import Kit.Query as Query

main = fn =>
  # Build a query with fluent chaining using |>> (data-last pipe)
  q = Query.create "posts"
    |>> Query.columns ["id", "title", "views"]
    |>> Query.filter "status" "=" "published"
    |>> Query.filter "views" ">" 10
    |>> Query.order-by "views" Query.Desc
    |>> Query.limit 10

  # Generate escaped SQL
  sql = Query.to-sql q
  println "SQL: ${sql}"
  # SQL: SELECT id, title, views FROM posts WHERE status = 'published' AND views > 10 ORDER BY views DESC LIMIT 10

  # Generate parameterized SQL with driver-specific placeholders
  (sqlite-sql, sqlite-params) = Query.to-sql-params "sqlite" q
  println "SQLite SQL: ${sqlite-sql}"
  println "SQLite params: ${sqlite-params}"
  # SQLite SQL: SELECT id, title, views FROM posts WHERE status = ?1 AND views > ?2 ORDER BY views DESC LIMIT 10

  (postgres-sql, postgres-params) = Query.to-sql-params "postgres" q
  println "Postgres SQL: ${postgres-sql}"
  println "Postgres params: ${postgres-params}"
  # Postgres SQL: SELECT id, title, views FROM posts WHERE status = $1 AND views > $2 ORDER BY views DESC LIMIT 10

  # String values are escaped for raw SQL output
  escaped = Query.create "posts"
    |>> Query.filter "title" "=" "Bob's Post"

  println "Escaped SQL: ${Query.to-sql escaped}"
  # Escaped SQL: SELECT * FROM posts WHERE title = 'Bob''s Post'

main

API Notes

• Query.create table starts a SELECT query for a table name.
• Query.columns, Query.filter, Query.order-by, Query.limit, Query.offset, and Query.typed are curried for |>> chaining.
• Query.to-sql returns escaped SQL for display, debugging, or drivers that only expose plain query.
• Query.to-sql-params returns (sql, params) and supports sqlite placeholders (?1) and postgres placeholders ($1). Unknown driver names use Postgres-style placeholders.
• Query.exec db q expects a database connection record with a query function and executes the escaped SQL produced by Query.to-sql.
• Query.typed records the desired result type in the query state, but it does not change generated SQL.

Related Packages

• kit-sqlite - SQLite bindings for Kit
• kit-postgres - PostgreSQL bindings for Kit using libpq

Development

Running Examples

Run examples with the interpreter:

kit run examples/sqlite-basic.kit
kit run examples/postgres-basic.kit

Compile examples to a native binary:

kit build examples/sqlite-basic.kit -o sqlite-basic && ./sqlite-basic
kit build examples/postgres-basic.kit -o postgres-basic && ./postgres-basic

Running Parity

Compare interpreter output with compiled binary output for the examples:

kit parity --no-spinner --failures-only

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:

1. Format and check source files in src/
2. 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/query/, making it available for import as Kit.Query in other projects.

License

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

Exported Functions & Types

Direction

Query Builder for Kit

A fluent, functional SQL query builder that works with any Kit database driver. Uses |>> (data-last pipe) for chaining operations.

import Query
import Postgres

type Post @table("posts") = Post(id @primary-key, title, status, created-at)

db = Postgres.connect "postgresql://localhost/mydb"

posts = Query.create "Post"
  |>> Query.filter "status" "=" "Published"
  |>> Query.order-by "created-at" Query.Desc
  |>> Query.limit 10
  |>> Query.typed "Post"
  |>> Query.exec db

# posts : Result (List Post) String

create

NonEmptyString -> QueryState

columns

List String -> QueryState -> QueryState

filter

String -> String -> a -> QueryState -> QueryState

order-by

String -> Direction -> QueryState -> QueryState

limit

NonNegativeInt -> QueryState -> QueryState

offset

NonNegativeInt -> QueryState -> QueryState

typed

NonEmptyString -> QueryState -> QueryState

to-sql

QueryState -> String

to-sql-params

String -> QueryState -> (String, List a)

exec

Ptr -> QueryState -> Result (List a) String

Asc

Ascending sort direction for ORDER BY clauses

Direction

Desc

Descending sort direction for ORDER BY clauses

Direction