SchemaScript

SchemaScript is an ECMAScript-based data-centric ORM that lets you declaratively define database schemas with maximum type safety and constraint enforcement. It's built as an abstraction over low-level backends like Drizzle ORM, offering a fluent API running securely within a sandboxed Rust runtime.

---

Features

• TypeScript (interface) .ts code generation.
• JSON schema .json code generation.
• JavaScript runtime validator .js code generation.
• SQL table creation & migration .sql code generation.

---

Getting Started

Installation

Use your favorite pacakge manager and install @artefacto/schemascript:

npm install -d @artefacto/schemascript

---

Usage

Schema Definition & Table Creation

Schemas are defined using the Schema function, which creates a type-safe schema definition that can be used for type generation and validation:

Tables are created using the Table function, which converts your schema definition into your targeted ORM table instance ready for database operations:

import type { SchemaBuilder } from "@artefacto/schemascript";
import { Schema, Table, value } from "@artefacto/schemascript";

const User: SchemaBuilder = (prop) => ({
	id: prop.integer().identifier(),
	username: prop.text().unique(),
	email: prop.text().optional(),
	created_at: prop.datetime().default(value.now),
});
const UserSchema = Schema("User", User);
const UserTable = Table("users", User);

export { User, UserSchema, UserTable };

---

Data Types

SchemaScript provides 8 core primitive data types:

SchemaScript Type	Description / Usage	JS Type	SQLite Type
integer	Whole number integer values	bigint	INTEGER
real	Floating-point real numbers	number	REAL
text	Textual string data	string	TEXT
boolean	True or false values	boolean	INTEGER (0 or 1)
blob	Binary data	Uint8Array	BLOB
datetime	Dates and times	Date	INTEGER
node	Structured objects and documents	object	BLOB (JSON)
enum	Performant, type-safe enumerations	string (union)	INTEGER

---

Modifiers

All properties support the following modifiers through method chaining:

• .identifier(): Marks the column as a primary key.
• .optional(): Allows the column to be null.
• .unique(): Adds a unique constraint (mapped to a unique index in SQLite).
• .default(value): Sets a default value. Supports literals and SQL expressions like value.now.
• .references(ref, actions?): Creates a foreign key constraint.
• .array(): Marks the column as an array.

Note: All fields are required (non-nullable) by default. Use .optional() to allow null values.

---

Relations

SchemaScript allows you to define database relationships between tables using the .references() modifier.

One-to-Many Relationship

import type { SchemaBuilder } from "@artefacto/schemascript";
import { Schema, Table } from "@artefacto/schemascript";
import { UserTable } from "./user";

const Post: SchemaBuilder = (prop) => ({
	id: prop.integer().identifier(),
	author_id: prop
		.integer()
		.references(() => UserTable.id, { onDelete: "cascade" }),
	title: prop.text(),
});

const PostSchema = Schema("Post", Post);
const PostTable = Table("posts", Post);

export { Post, PostSchema, PostTable };

---

Enums

First-class support for enums. Enums are defined using an object mapping keys to values or an array of strings. Column names are inferred from the object key.

const Profile = Schema("Profile", (prop) => ({
	role: prop.enum({ options: ["admin", "user", "guest"] }).default("guest"),
	status: prop.enum({ options: { ACTIVE: 1, INACTIVE: 0 } }).default("ACTIVE"),
}));

---

TypeScript Generation

SchemaScript can generate standard TypeScript interfaces from your schema definitions.

const userInterface = UserSchema.toTypeScriptInterface();
/*
interface User {
	id: bigint;
	username: string;
	email: string | null;
	created_at: Date;
}
*/

---

Architecture

The project is architected in three main domains, ensuring a hard boundary between high-level definition and low-level execution.

1. SchemaScript DSL (JavaScript)

A type-safe, fluent API for defining database schemas with SQLite-optimised primitives.

• Immutability: Every property modifier returns a new instance.
• Strict Naming: Column names are automatically and strictly inferred from object keys.
• Drizzle Integration: Definitions are translated into drizzle-orm compatible column builders.

2. High-Performance Runtime (Rust Host)

A secure execution environment leveraging WasmEdge and smol for ultra-fast, lightweight sandboxing.

3. The SYSCALL Bridge

Uses drizzle-orm/sqlite-proxy to capture SQL queries across the Host-Guest boundary.

---

License

This project is dedicated to the public domain under the CC0 1.0 Universal license.

---