Skip to main content

Introduction

danger

Kineo is very new, and its API is not stable at the moment. Expect major breaking changes.

Kineo is an Object-Relation/Graph Mapper, or an ORM. It maps your input objects into the correct query syntax. For example, this:

await db.users.findFirst({ where: { username: "john" } });

maps roughly to this:

SELECT * FROM "users" WHERE "username" = 'john' LIMIT 1;

and returns a typed JavaScript object, instead of unknown or any.

Installation​

Make sure you have Node.js >=20.19 and a package manager.

npm install kineo

Quick start​

Define a schema. This schema can be anywhere in your codebase, as long as you can reference it.

import { defineSchema, model, field, relation, type InferSchema } from "kineo";

export const schema = defineSchema({
  users: model("User", {
    name: field.string().id(),
    password: field.string().required(),
    posts: relation.to("Post").outgoing("HAS_POST").array(),
  }),

  posts: model("Post", {
    id: field.string().id(),
    title: field.string().required(),
    author: relation.to("User").incoming("HAS_POST"),
  }),
});

export type Schema = InferSchema<typeof schema>;

Create a client. Use an adapter, which is the set of functions that converts Kineo's representation to your database's query language. Here, we use the Neo4j adapter, which requires you to install neo4j-driver as a dependency.

import { kineo } from "kineo";
import { neo4jAdapter } from "kineo/adapters/neo4j";

export const db = kineo(
  neo4jAdapter({
    url: "bolt://localhost:7687",
    auth: {
      username: "neo4j",
      password: "password",
    },
  }),
  schema,
);

Different adapters will have different parameters.

Query your database. Kineo uses objects for querying.

const user = await db.users.findFirst({
  where: {
    name: {
      startsWith: "a",
      not: {
        endsWith: "z",
      },
    },
    AND: [
      {
        password: {
          contains: "secure",
        },
      },
    ],
  },
  include: {
    posts: true,
  },
});

Kineo also provides a way to manage your migrations, which you can see here.