@fizzog/sqlx 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# TypeScript SQL Engine
+
+A lightweight SQL engine written in TypeScript.
+
+`@fizzog/sqlx` is a small, experimental SQL implementation designed for learning how databases work internally. It includes a SQL lexer, parser, AST generation, and execution engine.
+
+The goal of this project is not to replace production databases, but to provide a simple and understandable implementation of SQL concepts.
+
+And perhaps, this can be something useful when more features are added.
+
+## Features
+
+Currently supported:
+
+* `CREATE TABLE`
+* `INSERT`
+* `SELECT`
+* `UPDATE`
+* `DELETE`
+* `WHERE` expressions
+* Multiple column selection
+* Multiple assignments in `UPDATE`
+
+Example:
+
+```sql
+CREATE TABLE users (id, name, age);
+
+INSERT INTO users VALUES (1, 'Alice', 30);
+
+SELECT * FROM users WHERE age > 18;
+
+UPDATE users SET age = 31 WHERE name = 'Alice';
+
+DELETE FROM users WHERE age < 18;
+```
+
+## Installation
+
+Install with npm:
+
+```bash
+npm install @fizzog/sqlx
+```
+
+or with Bun:
+
+```bash
+bun add @fizzog/sqlx
+```
+
+## Usage
+
+Import the engine and database classes:
+
+```ts
+import {
+  SqlEngine,
+  Database,
+  Table
+} from "@fizzog/sqlx";
+```
+
+Create a database:
+
+```ts
+const db = new Database();
+```
+
+Create a table:
+
+```ts
+db.addTable(
+    "users",               // name
+    ["id", "name", "age"], // columns
+    []                     // rows
+);
+```
+
+Create a SQL engine:
+
+```ts
+const engine = SqlEngine.start(db);
+```
+
+Execute SQL:
+
+```ts
+engine.consume(
+  "INSERT INTO users VALUES (1, 'Alice', 30);"
+);
+
+const users = engine.consume(
+  "SELECT * FROM users;"
+);
+
+console.log(users);
+```
+
+Output:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "Alice",
+    "age": 30
+  }
+]
+```
+
+## API
+
+### `SqlEngine.start(database)`
+
+Creates a new SQL engine instance.
+
+```ts
+const engine = SqlEngine.start(db);
+```
+
+### `engine.consume(sql)`
+
+Parses and executes a SQL statement.
+
+```ts
+const result = engine.consume(
+  "SELECT * FROM users;"
+);
+```
+
+Returns a JavaScript value depending on the SQL statement.
+
+Examples:
+
+`SELECT`:
+
+```ts
+[
+  {
+    id: 1,
+    name: "Alice",
+    age: 30
+  }
+]
+```
+
+`INSERT`:
+
+```ts
+{
+  inserted: 1
+}
+```
+
+`UPDATE`:
+
+```ts
+{
+  updated: 1
+}
+```
+
+`DELETE`:
+
+```ts
+{
+  deleted: 1
+}
+```
+
+## Architecture
+
+The engine processes SQL through several stages:
+
+```
+SQL String
+    |
+    v
+Lexer
+    |
+    v
+Tokens
+    |
+    v
+Parser
+    |
+    v
+Abstract Syntax Tree
+    |
+    v
+Executor
+    |
+    v
+Database
+```
+
+Each stage is intentionally separated to make the internals easier to understand and extend.
+
+## Limitations
+
+This project is intentionally simple.
+
+Current limitations include:
+
+* In-memory storage only
+* No persistence
+* No indexes
+* No joins
+* No transactions
+* Limited SQL syntax support
+* No type system enforcement
+
+## Project Status
+
+This project is primarily a learning project focused on understanding:
+
+* SQL parsing
+* Tokenization
+* AST design
+* Query execution
+* Database architecture concepts
+
+More SQL features will be added over time.
+
+## License
+
+MIT

package/dist/engine/SqlEngine.d.ts

@@ -0,0 +1,13 @@
+import type { Database } from "../storage/Database";
+export declare class SqlEngine {
+    private executor;
+    private constructor();
+    static start(db: Database): SqlEngine;
+    consume(sql: string): Record<string, unknown> | import("../storage/Table").Row[] | {
+        success: boolean;
+    } | {
+        updated: number;
+    } | {
+        deleted: number;
+    };
+}

package/dist/executor/Executor.d.ts

@@ -0,0 +1,19 @@
+import type { Statement } from "../parser/AST";
+import { Database } from "../storage/Database";
+export declare class Executor {
+    private db;
+    private expressionEvaluator;
+    constructor(db: Database);
+    execute(statement: Statement): Record<string, unknown> | import("../storage/Table").Row[] | {
+        success: boolean;
+    } | {
+        updated: number;
+    } | {
+        deleted: number;
+    };
+    private executeSelect;
+    private executeInsert;
+    private executeCreateTable;
+    private executeUpdate;
+    private executeDelete;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SqlEngine } from "./engine/SqlEngine";
+export { Database } from "./storage/Database";
+export { Table } from "./storage/Table";

package/dist/index.js

@@ -0,0 +1,566 @@
+// src/runtime/ExpressionEvaluator.ts
+class ExpressionEvaluator {
+  evaluate(expression, row) {
+    const left = row[expression.left];
+    if (typeof left !== "number" && typeof left !== "string") {
+      throw new Error(`Cannot compare value: ${String(left)}`);
+    }
+    switch (expression.operator) {
+      case ">":
+        return left > expression.right;
+      case "<":
+        return left < expression.right;
+      case "=":
+        return left === expression.right;
+      default:
+        throw new Error(`Unknown operator ${expression.operator}`);
+    }
+  }
+}
+
+// src/storage/Table.ts
+class Table {
+  name;
+  columns;
+  rows;
+  constructor(name, columns, rows) {
+    this.name = name;
+    this.columns = columns;
+    this.rows = rows;
+  }
+}
+
+// src/executor/Executor.ts
+class Executor {
+  db;
+  expressionEvaluator = new ExpressionEvaluator;
+  constructor(db) {
+    this.db = db;
+  }
+  execute(statement) {
+    switch (statement.type) {
+      case "SelectStatement":
+        return this.executeSelect(statement);
+      case "InsertStatement":
+        return this.executeInsert(statement);
+      case "CreateTableStatement":
+        return this.executeCreateTable(statement);
+      case "UpdateStatement":
+        return this.executeUpdate(statement);
+      case "DeleteStatement":
+        return this.executeDelete(statement);
+      default:
+        throw new Error(`Unsupported statement`);
+    }
+  }
+  executeSelect(statement) {
+    const table = this.db.getTable(statement.table);
+    let rows = table.rows;
+    if (statement.where) {
+      rows = rows.filter((row) => this.expressionEvaluator.evaluate(statement.where, row));
+    }
+    if (statement.columns.length === 1 && statement.columns[0] === "*") {
+      return rows;
+    }
+    return rows.map((row) => {
+      const result = {};
+      for (const column of statement.columns) {
+        result[column] = row[column];
+      }
+      return result;
+    });
+  }
+  executeInsert(statement) {
+    const table = this.db.getTable(statement.table);
+    if (statement.values.length !== table.columns.length) {
+      throw new Error("Number of values does not match number of columns");
+    }
+    const row = {};
+    table.columns.forEach((column, index) => {
+      row[column] = statement.values[index];
+    });
+    table.rows.push(row);
+    return row;
+  }
+  executeCreateTable(statement) {
+    this.db.addTable(new Table(statement.table, statement.columns, []));
+    return {
+      success: true
+    };
+  }
+  executeUpdate(statement) {
+    const table = this.db.getTable(statement.table);
+    let updated = 0;
+    for (const row of table.rows) {
+      if (statement.where && !this.expressionEvaluator.evaluate(statement.where, row)) {
+        continue;
+      }
+      for (const assignment of statement.assignments) {
+        row[assignment.column] = assignment.value;
+      }
+      updated++;
+    }
+    return {
+      updated
+    };
+  }
+  executeDelete(statement) {
+    const table = this.db.getTable(statement.table);
+    const originalCount = table.rows.length;
+    if (!statement.where) {
+      table.rows = [];
+    } else {
+      table.rows = table.rows.filter((row) => !this.expressionEvaluator.evaluate(statement.where, row));
+    }
+    return {
+      deleted: originalCount - table.rows.length
+    };
+  }
+}
+
+// src/lexer/Token.ts
+var TokenType;
+((TokenType2) => {
+  TokenType2[TokenType2["Keyword"] = 0] = "Keyword";
+  TokenType2[TokenType2["Identifier"] = 1] = "Identifier";
+  TokenType2[TokenType2["Semicolon"] = 2] = "Semicolon";
+  TokenType2[TokenType2["Asterisk"] = 3] = "Asterisk";
+  TokenType2[TokenType2["Number"] = 4] = "Number";
+  TokenType2[TokenType2["String"] = 5] = "String";
+  TokenType2[TokenType2["Operator"] = 6] = "Operator";
+  TokenType2[TokenType2["LeftParen"] = 7] = "LeftParen";
+  TokenType2[TokenType2["RightParen"] = 8] = "RightParen";
+  TokenType2[TokenType2["Comma"] = 9] = "Comma";
+  TokenType2[TokenType2["EOF"] = 10] = "EOF";
+})(TokenType ||= {});
+var keywords = new Set([
+  "SELECT",
+  "FROM",
+  "WHERE",
+  "INSERT",
+  "INTO",
+  "VALUES",
+  "UPDATE",
+  "DELETE",
+  "CREATE",
+  "TABLE",
+  "SET",
+  "DELETE"
+]);
+
+// src/lexer/Lexer.ts
+class Lexer {
+  input;
+  position = 0;
+  constructor(input) {
+    this.input = input;
+  }
+  tokenize() {
+    const tokens = [];
+    while (this.position < this.input.length) {
+      const char = this.input[this.position];
+      if (char === undefined)
+        break;
+      if (/\s/.test(char)) {
+        this.position++;
+        continue;
+      }
+      if (/[a-zA-Z_]/.test(char)) {
+        tokens.push(this.readWord());
+        continue;
+      }
+      if (/[0-9]/.test(char)) {
+        tokens.push(this.readNumber());
+        continue;
+      }
+      if (char === ";") {
+        tokens.push({
+          type: 2 /* Semicolon */,
+          value: ";"
+        });
+        this.position++;
+        continue;
+      }
+      if (char === "*") {
+        tokens.push({
+          type: 3 /* Asterisk */,
+          value: "*"
+        });
+        this.position++;
+        continue;
+      }
+      if (["=", ">", "<"].includes(char)) {
+        tokens.push({
+          type: 6 /* Operator */,
+          value: char
+        });
+        this.position++;
+        continue;
+      }
+      if (char === "'") {
+        tokens.push(this.readString());
+        continue;
+      }
+      if (char === "(") {
+        tokens.push({
+          type: 7 /* LeftParen */,
+          value: "("
+        });
+        this.position++;
+        continue;
+      }
+      if (char === ")") {
+        tokens.push({
+          type: 8 /* RightParen */,
+          value: ")"
+        });
+        this.position++;
+        continue;
+      }
+      if (char === ",") {
+        tokens.push({
+          type: 9 /* Comma */,
+          value: ","
+        });
+        this.position++;
+        continue;
+      }
+      throw new Error(`Unexpected character: ${char}`);
+    }
+    tokens.push({
+      type: 10 /* EOF */,
+      value: ""
+    });
+    return tokens;
+  }
+  readWord() {
+    let word = "";
+    while (this.position < this.input.length) {
+      const char = this.input[this.position];
+      if (!char || !/[a-zA-Z_]/.test(char)) {
+        break;
+      }
+      word += char;
+      this.position++;
+    }
+    const upper = word.toUpperCase();
+    if (keywords.has(upper)) {
+      return {
+        type: 0 /* Keyword */,
+        value: upper
+      };
+    }
+    return {
+      type: 1 /* Identifier */,
+      value: word
+    };
+  }
+  readNumber() {
+    let number = "";
+    while (this.position < this.input.length) {
+      const char = this.input[this.position];
+      if (!char || !/[0-9]/.test(char))
+        break;
+      number += char;
+      this.position++;
+    }
+    return {
+      type: 4 /* Number */,
+      value: number
+    };
+  }
+  readString() {
+    this.position++;
+    let value = "";
+    while (this.position < this.input.length && this.input[this.position] !== "'") {
+      value += this.input[this.position];
+      this.position++;
+    }
+    if (this.position >= this.input.length) {
+      throw new Error("Unterminated string literal");
+    }
+    this.position++;
+    return {
+      type: 5 /* String */,
+      value
+    };
+  }
+}
+
+// src/parser/TokenStream.ts
+class TokenStream {
+  tokens;
+  position = 0;
+  constructor(tokens) {
+    this.tokens = tokens;
+  }
+  current() {
+    return this.peek();
+  }
+  peek(offset = 0) {
+    const token = this.tokens[this.position + offset];
+    if (!token) {
+      throw new Error("Unexpected end of input");
+    }
+    return token;
+  }
+  advance() {
+    const token = this.current();
+    this.position++;
+    return token;
+  }
+  expect(type) {
+    const token = this.current();
+    if (token.type !== type) {
+      throw new Error(`Expected ${TokenType[type]}, got ${TokenType[token.type]}`);
+    }
+    this.position++;
+    return token;
+  }
+  expectKeyword(keyword) {
+    const token = this.expect(0 /* Keyword */);
+    if (token.value !== keyword) {
+      throw new Error(`Expected ${keyword}, got ${token.value}`);
+    }
+    return token;
+  }
+  expectIdentifier() {
+    return this.expect(1 /* Identifier */).value;
+  }
+}
+
+// src/parser/Parser.ts
+class Parser {
+  tokens;
+  stream;
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.stream = new TokenStream(tokens);
+  }
+  parse() {
+    const token = this.stream.current();
+    if (token.type !== 0 /* Keyword */) {
+      throw new Error("Expected statement");
+    }
+    switch (token.value) {
+      case "SELECT":
+        return this.parseSelect();
+      case "INSERT":
+        return this.parseInsert();
+      case "CREATE":
+        return this.parseCreateTable();
+      case "UPDATE":
+        return this.parseUpdate();
+      case "DELETE":
+        return this.parseDelete();
+      default:
+        throw new Error(`Unknown statement ${token.value}`);
+    }
+  }
+  parseSelect() {
+    this.expectKeyword("SELECT");
+    const columns = this.parseColumns();
+    this.expectKeyword("FROM");
+    const table = this.expectIdentifier();
+    let where;
+    if (this.stream.current().type === 0 /* Keyword */ && this.stream.current().value === "WHERE") {
+      this.stream.advance();
+      where = this.parseExpression();
+    }
+    return {
+      type: "SelectStatement",
+      columns,
+      table,
+      where
+    };
+  }
+  parseInsert() {
+    this.expectKeyword("INSERT");
+    this.expectKeyword("INTO");
+    const table = this.expectIdentifier();
+    this.expectKeyword("VALUES");
+    this.expect(7 /* LeftParen */);
+    const values = this.parseValues();
+    this.expect(8 /* RightParen */);
+    return {
+      type: "InsertStatement",
+      table,
+      values
+    };
+  }
+  parseCreateTable() {
+    this.stream.expectKeyword("CREATE");
+    this.stream.expectKeyword("TABLE");
+    const table = this.stream.expectIdentifier();
+    this.stream.expect(7 /* LeftParen */);
+    const columns = this.parseIdentifiers();
+    this.stream.expect(8 /* RightParen */);
+    return {
+      type: "CreateTableStatement",
+      table,
+      columns
+    };
+  }
+  parseValues() {
+    const values = [];
+    values.push(this.parseLiteral());
+    while (this.stream.current().type === 9 /* Comma */) {
+      this.stream.advance();
+      values.push(this.parseLiteral());
+    }
+    return values;
+  }
+  parseColumns() {
+    if (this.stream.current().type === 3 /* Asterisk */) {
+      this.stream.advance();
+      return ["*"];
+    }
+    const columns = [];
+    columns.push(this.expectIdentifier());
+    while (this.stream.current().type === 9 /* Comma */) {
+      this.stream.advance();
+      columns.push(this.expectIdentifier());
+    }
+    return columns;
+  }
+  expectKeyword(keyword) {
+    const token = this.expect(0 /* Keyword */);
+    if (token.value !== keyword) {
+      throw new Error(`Expected ${keyword}, got ${token.value}`);
+    }
+  }
+  expectIdentifier() {
+    return this.expect(1 /* Identifier */).value;
+  }
+  expect(type) {
+    const token = this.stream.current();
+    if (token.type !== type) {
+      throw new Error(`Expected ${TokenType[type]}, got ${TokenType[token.type]}`);
+    }
+    this.stream.advance();
+    return token;
+  }
+  parseLiteral() {
+    const token = this.stream.current();
+    switch (token.type) {
+      case 4 /* Number */:
+        this.stream.advance();
+        return Number(token.value);
+      case 5 /* String */:
+        this.stream.advance();
+        return token.value;
+      default:
+        throw new Error(`Expected literal, got ${token.value}`);
+    }
+  }
+  parseExpression() {
+    const left = this.expectIdentifier();
+    const operator = this.stream.current();
+    if (operator.type !== 6 /* Operator */) {
+      throw new Error(`Expected operator, got ${operator.value}`);
+    }
+    this.stream.advance();
+    return {
+      type: "BinaryExpression",
+      left,
+      operator: operator.value,
+      right: this.parseLiteral()
+    };
+  }
+  parseIdentifiers() {
+    const identifiers = [];
+    identifiers.push(this.stream.expectIdentifier());
+    while (this.stream.current().type === 9 /* Comma */) {
+      this.stream.expect(9 /* Comma */);
+      identifiers.push(this.stream.expectIdentifier());
+    }
+    return identifiers;
+  }
+  parseUpdate() {
+    this.stream.expectKeyword("UPDATE");
+    const table = this.stream.expectIdentifier();
+    this.stream.expectKeyword("SET");
+    const assignments = this.parseAssignments();
+    let where;
+    if (this.stream.current().value === "WHERE") {
+      this.stream.expectKeyword("WHERE");
+      where = this.parseExpression();
+    }
+    return {
+      type: "UpdateStatement",
+      table,
+      assignments,
+      where
+    };
+  }
+  parseAssignments() {
+    const assignments = [];
+    assignments.push(this.parseAssignment());
+    while (this.stream.current().type === 9 /* Comma */) {
+      this.stream.expect(9 /* Comma */);
+      assignments.push(this.parseAssignment());
+    }
+    return assignments;
+  }
+  parseAssignment() {
+    const column = this.stream.expectIdentifier();
+    this.stream.expect(6 /* Operator */);
+    const value = this.parseLiteral();
+    return {
+      column,
+      value
+    };
+  }
+  parseDelete() {
+    this.stream.expectKeyword("DELETE");
+    this.stream.expectKeyword("FROM");
+    const table = this.stream.expectIdentifier();
+    let where;
+    if (this.stream.current().value === "WHERE") {
+      this.stream.expectKeyword("WHERE");
+      where = this.parseExpression();
+    }
+    return {
+      type: "DeleteStatement",
+      table,
+      where
+    };
+  }
+}
+
+// src/engine/SqlEngine.ts
+class SqlEngine {
+  executor;
+  constructor(executor) {
+    this.executor = executor;
+  }
+  static start(db) {
+    return new SqlEngine(new Executor(db));
+  }
+  consume(sql) {
+    const lexer = new Lexer(sql);
+    const tokens = lexer.tokenize();
+    const parser = new Parser(tokens);
+    const statement = parser.parse();
+    return this.executor.execute(statement);
+  }
+}
+// src/storage/Database.ts
+class Database {
+  tables = new Map;
+  addTable(table) {
+    this.tables.set(table.name, table);
+  }
+  getTable(name) {
+    const table = this.tables.get(name);
+    if (!table) {
+      throw new Error(`Table ${name} does not exist`);
+    }
+    return table;
+  }
+}
+export {
+  Table,
+  SqlEngine,
+  Database
+};

package/dist/lexer/Lexer.d.ts

@@ -0,0 +1,10 @@
+import { type Token } from "./Token";
+export declare class Lexer {
+    private input;
+    private position;
+    constructor(input: string);
+    tokenize(): Token[];
+    private readWord;
+    private readNumber;
+    private readString;
+}

package/dist/lexer/Token.d.ts

@@ -0,0 +1,18 @@
+export declare enum TokenType {
+    Keyword = 0,
+    Identifier = 1,
+    Semicolon = 2,
+    Asterisk = 3,
+    Number = 4,
+    String = 5,
+    Operator = 6,
+    LeftParen = 7,
+    RightParen = 8,
+    Comma = 9,
+    EOF = 10
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+}
+export declare const keywords: Set<string>;

package/dist/parser/AST.d.ts

@@ -0,0 +1,38 @@
+export interface SelectStatement {
+    type: "SelectStatement";
+    columns: string[];
+    table: string;
+    where?: BinaryExpression;
+}
+export interface InsertStatement {
+    type: "InsertStatement";
+    table: string;
+    values: (string | number)[];
+}
+export interface CreateTableStatement {
+    type: "CreateTableStatement";
+    table: string;
+    columns: string[];
+}
+export interface BinaryExpression {
+    type: "BinaryExpression";
+    left: string;
+    operator: string;
+    right: string | number;
+}
+export interface Assignment {
+    column: string;
+    value: string | number;
+}
+export interface UpdateStatement {
+    type: "UpdateStatement";
+    table: string;
+    assignments: Assignment[];
+    where?: BinaryExpression;
+}
+export interface DeleteStatement {
+    type: "DeleteStatement";
+    table: string;
+    where?: BinaryExpression;
+}
+export type Statement = SelectStatement | InsertStatement | CreateTableStatement | UpdateStatement | DeleteStatement;

package/dist/parser/Parser.d.ts

@@ -0,0 +1,23 @@
+import { type Token } from "../lexer/Token";
+import type { Statement } from "./AST";
+export declare class Parser {
+    private tokens;
+    private stream;
+    constructor(tokens: Token[]);
+    parse(): Statement;
+    private parseSelect;
+    private parseInsert;
+    private parseCreateTable;
+    private parseValues;
+    private parseColumns;
+    private expectKeyword;
+    private expectIdentifier;
+    private expect;
+    private parseLiteral;
+    private parseExpression;
+    private parseIdentifiers;
+    private parseUpdate;
+    private parseAssignments;
+    private parseAssignment;
+    private parseDelete;
+}

package/dist/parser/TokenStream.d.ts

@@ -0,0 +1,12 @@
+import { TokenType, type Token } from "../lexer/Token";
+export declare class TokenStream {
+    private tokens;
+    private position;
+    constructor(tokens: Token[]);
+    current(): Token;
+    peek(offset?: number): Token;
+    advance(): Token;
+    expect(type: TokenType): Token;
+    expectKeyword(keyword: string): Token;
+    expectIdentifier(): string;
+}

package/dist/runtime/ExpressionEvaluator.d.ts

@@ -0,0 +1,4 @@
+import type { BinaryExpression } from "../parser/AST";
+export declare class ExpressionEvaluator {
+    evaluate(expression: BinaryExpression, row: Record<string, unknown>): boolean;
+}

package/dist/storage/Database.d.ts

@@ -0,0 +1,6 @@
+import { Table } from "./Table";
+export declare class Database {
+    private tables;
+    addTable(table: Table): void;
+    getTable(name: string): Table;
+}

package/dist/storage/Table.d.ts

@@ -0,0 +1,7 @@
+export type Row = Record<string, unknown>;
+export declare class Table {
+    name: string;
+    columns: string[];
+    rows: Row[];
+    constructor(name: string, columns: string[], rows: Row[]);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@fizzog/sqlx",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "start": "bun run src/cli.ts",
+    "test": "bun test",
+    "dry": "npm pack --dry-run",
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}