cl-orm 0.1.0

package/.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.yml]
+indent_style = space

package/.gitattributes

@@ -0,0 +1 @@
+website/** linguist-documentation

package/.prettierignore

@@ -0,0 +1,3 @@
+/lib
+/CHANGELOG.md
+/website

package/.prettierrc

@@ -0,0 +1,34 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "proseWrap": "preserve",
+  "endOfLine": "auto",
+  "embeddedLanguageFormatting": "auto",
+  "singleAttributePerLine": false,
+  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
+  "importOrder": [
+    "<TYPES>^(node:)",
+    "<TYPES>",
+    "<TYPES>^[.]",
+    "<BUILTIN_MODULES>",
+    "<THIRD_PARTY_MODULES>",
+    "^[.]"
+  ],
+  "overrides": [
+    {
+      "files": "*.jsonc",
+      "options": {
+        "trailingComma": "none"
+      }
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "editor.trimAutoWhitespace": true,
+  "editor.indentSize": 2,
+  "editor.tabSize": 2,
+  "editor.formatOnSave": true,
+  "files.trimTrailingWhitespace": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll": "explicit"
+  },
+  "[markdown]": {
+    "files.trimTrailingWhitespace": false
+  }
+}

package/README.md

@@ -0,0 +1,105 @@
+# CL ORM
+
+<img align="right" width="64" height="64" alt="Logo" src="website/static/img/favicon.svg">
+
+A lightweight **ORM** for **Cloudflare Workers** (**D1** and **Durable Objects**), designed to be intuitive, productive and focused on essential functionality.
+
+- This project supports **Cloudflare D1** and **Durable Objects SQL Storage** as database drivers.
+
+---
+
+📘 [**Documentation**](https://wellwelwel.github.io/cl-orm/docs/)
+
+---
+
+## Why
+
+- Supports both **Cloudflare D1** and **Durable Objects** SQL Storage.
+- Unified **Connection** interface across different database drivers.
+- An user-friendly ORM for **INSERT**, **SELECT**, **UPDATE**, **DELETE** and **WHERE** clauses.
+- Automatic **Prepared Statements** (including **LIMIT** and **OFFSET**).
+
+---
+
+## Documentation
+
+See detailed specifications and usage in [**Documentation**](https://wellwelwel.github.io/cl-orm/docs/category/documentation) section for queries, advanced concepts and much more.
+
+---
+
+## Quickstart
+
+### Installation
+
+```shell
+npm i cl-orm
+```
+
+---
+
+### Connect
+
+#### D1
+
+```ts
+import { useD1 } from 'cl-orm';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const db = useD1(env.DB);
+
+    await db.query('SELECT 1');
+    // ...
+  },
+};
+```
+
+#### Durable Objects
+
+```ts
+import { useDO } from 'cl-orm';
+import { DurableObject } from 'cloudflare:workers';
+
+export class MyDurableObject extends DurableObject {
+  async fetch(request: Request): Promise<Response> {
+    const db = useDO(this.ctx.storage.sql);
+
+    await db.query('SELECT 1');
+    // ...
+  }
+}
+```
+
+---
+
+### Basic Usage Example
+
+The following example is based on **TypeScript** and **ES Modules**.
+
+```ts
+import type { Connection } from 'cl-orm';
+import { OP } from 'cl-orm';
+
+export const getUser = async (db: Connection, id: number) => {
+  const user = await db.select({
+    table: 'users',
+    where: OP.eq('id', id),
+    limit: 1,
+  });
+
+  return user;
+};
+
+// Usage: await getUser(db, 15);
+```
+
+- See all available operators (**OP**) [here](https://wellwelwel.github.io/cl-orm/docs/category/operators).
+- Due to `limit: 1`, it returns a direct object with the row result or `null`.
+
+---
+
+## Acknowledgements
+
+- The operator names **eq**, **ne**, **gt**, **lt**, **gte** and **lte** are inspired by [**Sequelize**](https://sequelize.org/docs/v6/core-concepts/model-querying-basics/#operators).
+- [**Contributors**](https://github.com/wellwelwel/cl-orm/graphs/contributors).
+- This project is adapted from [**MySQL2 ORM**](https://github.com/wellwelwel/mysql2-orm).

package/mcr.config.ts

@@ -0,0 +1,12 @@
+import type { CoverageReportOptions } from 'monocart-coverage-reports';
+
+const coverageOptions: CoverageReportOptions = {
+  reports: ['v8', 'console-details', 'codecov'],
+  entryFilter: {
+    '**/node_modules/**': false,
+    '**/test/**': false,
+    '**/src/**': true,
+  },
+};
+
+export default coverageOptions;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "cl-orm",
+  "version": "0.1.0",
+  "description": "A lightweight ORM for Cloudflare Workers (D1 and Durable Objects), designed to be intuitive, productive and focused on essential functionality",
+  "scripts": {
+    "dev:d1": "wrangler dev --config test/__fixtures__/d1/wrangler.jsonc --port 8787 --inspector-port 9229",
+    "dev:do": "wrangler dev --config test/__fixtures__/do/wrangler.jsonc --port 8788 --inspector-port 9230",
+    "prebuild": "rm -rf lib",
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
+    "test": "poku test",
+    "test:coverage": "mcr --import tsx --config mcr.config.ts npm run test",
+    "typecheck": "tsc --noEmit",
+    "update": "pu && npm i && npm update && (npm audit fix || true)",
+    "postupdate": "npm run lint:fix"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260130.0",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.0",
+    "@types/node": "^25.1.0",
+    "monocart-coverage-reports": "^2.12.9",
+    "packages-update": "^2.0.0",
+    "poku": "^3.0.3-canary.13a996a9",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "wrangler": "^4.61.1"
+  }
+}

package/src/drivers/_utils.ts

@@ -0,0 +1,31 @@
+import type { Meta } from '../types.js';
+
+export const returnsRows = (sql: string): boolean => {
+  const trimmed = sql.trimStart().toUpperCase();
+
+  return (
+    trimmed.indexOf('SELECT') === 0 ||
+    trimmed.indexOf('WITH') === 0 ||
+    trimmed.indexOf('PRAGMA') === 0 ||
+    trimmed.indexOf('RETURNING') !== -1
+  );
+};
+
+export const prepare = (
+  db: D1Database,
+  sql: string,
+  params: unknown[]
+): D1PreparedStatement =>
+  params.length > 0 ? db.prepare(sql).bind(...params) : db.prepare(sql);
+
+export const setMeta = (
+  cursor: SqlStorageCursor<Record<string, SqlStorageValue>>
+): Meta => ({
+  duration: 0,
+  size_after: 0,
+  rows_read: cursor.rowsRead,
+  rows_written: cursor.rowsWritten,
+  last_row_id: 0,
+  changed_db: cursor.rowsWritten > 0,
+  changes: cursor.rowsWritten,
+});

package/src/drivers/d1.ts

@@ -0,0 +1,70 @@
+import type {
+  Connection,
+  DeleteOptions,
+  InsertOptions,
+  Meta,
+  QueryResult,
+  SelectOptions,
+  UpdateOptions,
+} from '../types.js';
+import { buildDelete } from '../queries/delete.js';
+import { buildInsert } from '../queries/insert.js';
+import { buildSelect } from '../queries/select.js';
+import { buildUpdate } from '../queries/update.js';
+import { prepare, returnsRows } from './_utils.js';
+
+export const useD1 = (db: D1Database): Connection => {
+  const query = async <T = Record<string, unknown>>(
+    sql: string,
+    values?: unknown[]
+  ): Promise<QueryResult<T>> => {
+    const statement = values
+      ? db.prepare(sql).bind(...values)
+      : db.prepare(sql);
+
+    if (returnsRows(sql)) {
+      const { results, meta } = await statement.all<T>();
+      return { rows: results, meta: meta as Meta };
+    }
+
+    const { meta } = await statement.run();
+    return { rows: [], meta: meta as Meta };
+  };
+
+  const select = async <T = Record<string, unknown>>(
+    options: SelectOptions
+  ): Promise<T | null | T[]> => {
+    const { sql, params } = buildSelect(options);
+    const statement = prepare(db, sql, params);
+
+    if (options.limit === 1) return statement.first<T>();
+
+    const { results } = await statement.all<T>();
+    return results;
+  };
+
+  const insert = async (options: InsertOptions): Promise<Meta> => {
+    const { sql, params } = buildInsert(options);
+    const { meta } = await query(sql, params);
+
+    return meta;
+  };
+
+  const update = async (options: UpdateOptions): Promise<Meta> => {
+    const { sql, params } = buildUpdate(options);
+    const statement = prepare(db, sql, params);
+    const { meta } = await statement.run();
+
+    return meta as Meta;
+  };
+
+  const del = async (options: DeleteOptions): Promise<Meta> => {
+    const { sql, params } = buildDelete(options);
+    const statement = prepare(db, sql, params);
+    const { meta } = await statement.run();
+
+    return meta as Meta;
+  };
+
+  return { query, select, insert, update, delete: del };
+};

package/src/drivers/do.ts

@@ -0,0 +1,81 @@
+import type {
+  Connection,
+  DeleteOptions,
+  InsertOptions,
+  Meta,
+  QueryResult,
+  SelectOptions,
+  UpdateOptions,
+} from '../types.js';
+import { buildDelete } from '../queries/delete.js';
+import { buildInsert } from '../queries/insert.js';
+import { buildSelect } from '../queries/select.js';
+import { buildUpdate } from '../queries/update.js';
+import { returnsRows, setMeta } from './_utils.js';
+
+export const useDO = (sql: SqlStorage): Connection => {
+  const exec = <T extends Record<string, SqlStorageValue>>(
+    query: string,
+    values?: unknown[]
+  ) => (values ? sql.exec<T>(query, ...values) : sql.exec<T>(query));
+
+  const query = async <T = Record<string, unknown>>(
+    queryStr: string,
+    values?: unknown[]
+  ): Promise<QueryResult<T>> => {
+    const cursor = exec(queryStr, values);
+
+    if (returnsRows(queryStr)) {
+      const rows = cursor.toArray() as T[];
+      return { rows, meta: setMeta(cursor) };
+    }
+
+    return { rows: [], meta: setMeta(cursor) };
+  };
+
+  const select = async <T = Record<string, unknown>>(
+    options: SelectOptions
+  ): Promise<T | null | T[]> => {
+    const built = buildSelect(options);
+    const cursor = exec(
+      built.sql,
+      built.params.length > 0 ? built.params : undefined
+    );
+
+    if (options.limit === 1) {
+      const rows = cursor.toArray() as T[];
+      return rows[0] ?? null;
+    }
+
+    return cursor.toArray() as T[];
+  };
+
+  const insert = async (options: InsertOptions): Promise<Meta> => {
+    const built = buildInsert(options);
+    const cursor = exec(built.sql, built.params);
+
+    return setMeta(cursor);
+  };
+
+  const update = async (options: UpdateOptions): Promise<Meta> => {
+    const built = buildUpdate(options);
+    const cursor = exec(
+      built.sql,
+      built.params.length > 0 ? built.params : undefined
+    );
+
+    return setMeta(cursor);
+  };
+
+  const del = async (options: DeleteOptions): Promise<Meta> => {
+    const built = buildDelete(options);
+    const cursor = exec(
+      built.sql,
+      built.params.length > 0 ? built.params : undefined
+    );
+
+    return setMeta(cursor);
+  };
+
+  return { query, select, insert, update, delete: del };
+};

package/src/index.ts

@@ -0,0 +1,13 @@
+export { useD1 } from './drivers/d1.js';
+export { useDO } from './drivers/do.js';
+export { OP } from './queries/where/operators.js';
+
+export type {
+  QueryResult,
+  Connection,
+  Meta,
+  Condition,
+  Param,
+  WhereClause,
+  WhereItem,
+} from './types.js';

package/src/queries/_utils.ts

@@ -0,0 +1,10 @@
+export const quoteIdentifier = (name: string): string => {
+  if (name.includes('.')) {
+    return name
+      .split('.')
+      .map((part) => `\`${part}\``)
+      .join('.');
+  }
+
+  return `\`${name}\``;
+};

package/src/queries/delete.ts

@@ -0,0 +1,26 @@
+import type { DeleteOptions } from '../types.js';
+import { quoteIdentifier } from './_utils.js';
+import { buildWhere } from './where/where.js';
+
+export const buildDelete = (
+  options: DeleteOptions
+): { sql: string; params: unknown[] } => {
+  const parts: string[] = ['DELETE FROM', quoteIdentifier(options.table)];
+  const params: unknown[] = [];
+
+  if (options.where) {
+    const where = buildWhere(options.where);
+
+    parts.push('WHERE', where.sql);
+    params.push(...where.params);
+  }
+
+  if (options.limit !== undefined) {
+    parts.push('LIMIT ?');
+    params.push(options.limit);
+  }
+
+  if (options.params) params.unshift(...options.params);
+
+  return { sql: parts.join(' '), params };
+};

package/src/queries/insert.ts

@@ -0,0 +1,22 @@
+import type { InsertOptions } from '../types.js';
+import { quoteIdentifier } from './_utils.js';
+
+export const buildInsert = (
+  options: InsertOptions
+): { sql: string; params: unknown[] } => {
+  const rows = Array.isArray(options.values)
+    ? options.values
+    : [options.values];
+  const columns = Object.keys(rows[0]);
+
+  const columnsSql = columns.map(quoteIdentifier).join(', ');
+  const placeholders = `(${columns.map(() => '?').join(', ')})`;
+  const valuesSql = rows.map(() => placeholders).join(', ');
+
+  const params = rows.flatMap((row) => columns.map((col) => row[col]));
+
+  return {
+    sql: `INSERT INTO ${quoteIdentifier(options.table)} (${columnsSql}) VALUES ${valuesSql}`,
+    params,
+  };
+};

package/src/queries/select.ts

@@ -0,0 +1,64 @@
+import type { JoinOptions, SelectOptions } from '../types.js';
+import { quoteIdentifier } from './_utils.js';
+import { buildWhere } from './where/where.js';
+
+const buildColumns = (columns?: string | string[]): string => {
+  if (!columns) return '*';
+  if (typeof columns === 'string') return columns;
+
+  return columns.map(quoteIdentifier).join(', ');
+};
+
+const buildJoin = (join: JoinOptions): string => {
+  const type = join.outer
+    ? `${join.type.toUpperCase()} OUTER`
+    : join.type.toUpperCase();
+
+  return `${type} JOIN ${quoteIdentifier(join.table)} ON ${quoteIdentifier(join.on.a)} = ${quoteIdentifier(join.on.b)}`;
+};
+
+export const buildSelect = (
+  options: SelectOptions
+): { sql: string; params: unknown[] } => {
+  const parts: string[] = ['SELECT'];
+  const params: unknown[] = [];
+
+  if (options.distinct) parts.push('DISTINCT');
+
+  parts.push(buildColumns(options.columns));
+  parts.push('FROM', quoteIdentifier(options.table));
+
+  if (options.join) {
+    const joins = Array.isArray(options.join) ? options.join : [options.join];
+    for (const join of joins) {
+      parts.push(buildJoin(join));
+    }
+  }
+
+  if (options.where) {
+    const where = buildWhere(options.where);
+    parts.push('WHERE', where.sql);
+    params.push(...where.params);
+  }
+
+  if (options.groupBy) parts.push('GROUP BY', quoteIdentifier(options.groupBy));
+
+  if (options.orderBy) {
+    const [column, direction = 'ASC'] = options.orderBy;
+    parts.push('ORDER BY', quoteIdentifier(column), direction);
+  }
+
+  if (options.limit !== undefined) {
+    parts.push('LIMIT ?');
+    params.push(options.limit);
+  }
+
+  if (options.offset !== undefined) {
+    parts.push('OFFSET ?');
+    params.push(options.offset);
+  }
+
+  if (options.params) params.unshift(...options.params);
+
+  return { sql: parts.join(' '), params };
+};

package/src/queries/update.ts

@@ -0,0 +1,28 @@
+import type { UpdateOptions } from '../types.js';
+import { quoteIdentifier } from './_utils.js';
+import { buildWhere } from './where/where.js';
+
+export const buildUpdate = (
+  options: UpdateOptions
+): { sql: string; params: unknown[] } => {
+  const columns = Object.keys(options.set);
+  const setSql = columns.map((col) => `${quoteIdentifier(col)} = ?`).join(', ');
+  const params: unknown[] = columns.map((col) => options.set[col]);
+
+  const parts: string[] = [
+    'UPDATE',
+    quoteIdentifier(options.table),
+    'SET',
+    setSql,
+  ];
+
+  if (options.where) {
+    const where = buildWhere(options.where);
+    parts.push('WHERE', where.sql);
+    params.push(...where.params);
+  }
+
+  if (options.params) params.push(...options.params);
+
+  return { sql: parts.join(' '), params };
+};

package/src/queries/where/operators.ts

@@ -0,0 +1,96 @@
+import type { Condition, Param } from '../../types.js';
+import { quoteIdentifier } from '../_utils.js';
+
+const comparison = (
+  column: string,
+  operator: string,
+  param: Param
+): Condition => ({
+  condition: `${quoteIdentifier(column)} ${operator} ?`,
+  params: [param],
+});
+
+export const OP = {
+  eq: (column: string, param: Param): Condition =>
+    comparison(column, '=', param),
+  ne: (column: string, param: Param): Condition =>
+    comparison(column, '!=', param),
+  gt: (column: string, param: Param): Condition =>
+    comparison(column, '>', param),
+  lt: (column: string, param: Param): Condition =>
+    comparison(column, '<', param),
+  gte: (column: string, param: Param): Condition =>
+    comparison(column, '>=', param),
+  lte: (column: string, param: Param): Condition =>
+    comparison(column, '<=', param),
+  like: (column: string, param: Param): Condition =>
+    comparison(column, 'LIKE', param),
+  notLike: (column: string, param: Param): Condition =>
+    comparison(column, 'NOT LIKE', param),
+
+  isNull: (column: string): Condition => ({
+    condition: `${quoteIdentifier(column)} IS NULL`,
+    params: [],
+  }),
+
+  isNotNull: (column: string): Condition => ({
+    condition: `${quoteIdentifier(column)} IS NOT NULL`,
+    params: [],
+  }),
+
+  in: ((
+    column: string,
+    valuesOrSubquery: Param[] | string,
+    subqueryParams?: Param[]
+  ): Condition => {
+    if (typeof valuesOrSubquery === 'string') {
+      return {
+        condition: `${quoteIdentifier(column)} IN (${valuesOrSubquery})`,
+        params: subqueryParams ?? [],
+      };
+    }
+
+    const placeholders = valuesOrSubquery.map(() => '?').join(', ');
+
+    return {
+      condition: `${quoteIdentifier(column)} IN (${placeholders})`,
+      params: valuesOrSubquery,
+    };
+  }) as {
+    (column: string, params: Param[]): Condition;
+    (column: string, subquery: string, params: Param[]): Condition;
+  },
+
+  notIn: ((
+    column: string,
+    valuesOrSubquery: Param[] | string,
+    subqueryParams?: Param[]
+  ): Condition => {
+    if (typeof valuesOrSubquery === 'string') {
+      return {
+        condition: `${quoteIdentifier(column)} NOT IN (${valuesOrSubquery})`,
+        params: subqueryParams ?? [],
+      };
+    }
+
+    const placeholders = valuesOrSubquery.map(() => '?').join(', ');
+
+    return {
+      condition: `${quoteIdentifier(column)} NOT IN (${placeholders})`,
+      params: valuesOrSubquery,
+    };
+  }) as {
+    (column: string, params: Param[]): Condition;
+    (column: string, subquery: string, params: Param[]): Condition;
+  },
+
+  between: (column: string, params: [Param, Param]): Condition => ({
+    condition: `${quoteIdentifier(column)} BETWEEN ? AND ?`,
+    params,
+  }),
+
+  notBetween: (column: string, params: [Param, Param]): Condition => ({
+    condition: `${quoteIdentifier(column)} NOT BETWEEN ? AND ?`,
+    params,
+  }),
+};