cirql

---

Cirql (pronounced Circle) is a simple and lightweight ORM and query builder for SurrealDB with built in model mapping and validation powered by Zod. Unlike most query builders, Cirql takes a very open approach, providing you with complete control over your queries.

Features

• 🔗 Connect to SurrealDB over stateful WebSockets or stateless requests
• 📦 Immutable query chaining for batching & transactions
• ⚙️ Zod-powered schema validation of query results
• 📝 Full TypeScript support with Zod schema inference
• 💎 Write flexible queries using strings or via chained functions

Notice

Cirql is still in early developmental stages. While you can use it for production applications, it may still lack specific features and edge cases. Feel free to submit feature requests or pull requests to add additional functionality to Cirql. We do ask you to please read our Contributor Guide.

While we try to prevent making any significant API changes, we cannot guarantee this.

Installation

The first step to use Cirql is to install the package from npm, together with a supported version of zod.

npm install cirql zod

Getting started

Navigation

• Connecting to SurrealDB
• String based queries
• Result validation & TypeScript typings
• Simplified create & update queries
• Writing programmatic queries
• Batched queries & transactions
• Stateless requests

Connecting to SurrealDB

You can now instantiate a Cirql instance which will automatically attempt to connect to SurrealDB. If you require manual control over connecting you can disable auto connect in the options.

import { Cirql } from 'cirql';

const cirql = new Cirql({
    connection: {
        endpoint: 'http://localhost:8000/',
        namespace: 'test',
        database: 'test',
    },
    credentials: {
        user: 'root',
        pass: 'root',
    }
});

String based queries

Once you have your cirql connection opened, you will be able to execute queries on the database.

const profiles = await cirql.selectMany({ 
    query: 'SELECT * FROM profile WHERE age > $minAge',
    params: {
        minAge: 42
    }
});

In order to prevent potential SQL injection attacks avoid inserting user-generated variables directly into your queries. Instead, make use of Surreal's parameter functionality as demonstrated above.

If you need more control over your query you can also use the query() function to send any query string with no limitations.

Result validation & TypeScript typings

By utilizing zod, Cirql is able to efficiently validate query responses against predefined schemas. While specifying schemas is useful for client-side record validation, it also has the added benefit of providing full type completion for TypeScript codebases.

const UserProfile = z.object({
    firstName: z.string(),
    lastName: z.string(),
    createdAt: z.string(),
    email: z.string(),
    age: z.number()
});

const profiles = await cirql.selectMany({ 
    query: 'SELECT * FROM profile WHERE age > $minAge',
    schema: UserProfile,
    params: {
        minAge: 42
    }
});

// 'profiles' is of type UserProfile[]

Simplified create & update queries

Using the query functions for sending create and update queries will allow you to provide any JavaScript object which will be automatically serialized. You can use the eq function to insert raw query values such as SurrealDB functions.

await cirql.create({
    table: 'profile',
    schema: UserProfile,
    data: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[e-mail]',
        createdAt: eq('time::now()'),
        age: 42
    }
});

When adding or subtracting items from arrays, you can use the add and remove functions for inserting += and -= operators.

Writing programmatic queries

Having to write your queries as plain strings is fine for most use-cases, however Cirql also provides an API for writing programmatic queries. You can pass these directly to any operation expecting a query and will automatically convert your input to a string.

You can import any of Surreal's comparison operators for use in your WHERE clause. You can find a complete list here. By default values will use a simple value comparison (=).

await cirql.selectOne({
    schema: UserProfile,
    params: {
        name: "John"
    },
    query: select()
        .from('profile')
        .where({
            firstName: eq(raw('$name')),
            lastName: 'Doe',
            age: 42
        })
        .fetch('friends', 'activities')
        .orderBy({
            createdAt: 'desc'
        })
});

For added convinience, passing a programmatic query to selectOne will automatically set its limit to 1.

Batched queries & transactions

You can send multiple queries in a single request by chaining multiple operations together after using the .prepare() function. The execute function will return a spreadable array containing all query results.

const [profiles, total, john] = cirql.prepare()
    .selectMany({ 
        query: select().from('profile'),
        schema: UserProfile
    })
    .count({
        table: 'userProfile'
    })
    .create({
        table: 'userProfile',
        schema: UserProfile,
        data: {
            firstName: 'John',
            localhost: 'Doe',
            email: '[e-mail]',
            createdAt: eq('time::now()'),
            age: 42
        }
    })
    .execute();

If you would like to run the batched queries as transaction instead, simply replace .execute() with .transaction().

Stateless requests

When making requests from environments where execution times might be short lived, or where you don't need to maintain persistence between requests, you can run Cirql in stateless mode. This will cause Cirql to make individual HTTP requests for each query.

You can easily construct a stateless Cirql instance, execute a query, and discard it without having to close a connection. Keep in mind that stateless requests may take longer than stateful requests, so this is not recommended for long-running applications.

import { CirqlStateless } from 'cirql';

const cirql = new CirqlStateless({
    connection: {
        endpoint: 'http://localhost:8000/',
        namespace: 'test',
        database: 'test',
    },
    credentials: {
        user: 'root',
        pass: 'root',
    }
});

// You can now use the cirql instance as normal without
// having to call .disconnect()

const profiles = await cirql.selectMany({ 
    query: 'SELECT * FROM profile WHERE age > $minAge',
    params: {
        minAge: 42
    }
});

Contributing

We welcome any issues and PRs submitted to Cirql. Since we currently work on multiple other projects and our time is limited, we value any community help in supporting a rich future for Cirql.

Before you open an issue or PR please read our Contributor Guide.

Requirements

• PNPM (npm i -g pnpm)

Roadmap

You can find the roadmap of intended features here.

Changelog

The changelog of previous versions can be found here.

Live Development

To run in live development mode, run pnpm dev in the project directory. This will start the Vite development server.

Maintainers

Cirql is built and maintained by Starlane Studios at no cost. If you would like to support our work feel free to donate to us ⚡

License

Cirql is licensed under MIT

Copyright (c) 2023, Starlane Studios