cl-orm 0.1.0

package/website/docs/documentation/queries/select.mdx

@@ -0,0 +1,294 @@
+---
+sidebar_position: 1
+---
+
+# SELECT
+
+> For **WHERE** examples, please see the **WHERE** section.
+
+## Simple SELECT
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+/**
+ * @return T[]
+ */
+await db.select({
+  table: 'test',
+});
+```
+
+> SQL Query
+
+```sql
+SELECT * FROM test
+```
+
+<hr />
+
+## SELECT (columns: string[])
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+/**
+ * @return T[]
+ */
+await db.select({
+  table: 'test',
+  columns: ['foo'],
+});
+```
+
+> SQL Query
+
+```sql
+SELECT foo FROM test
+```
+
+<hr />
+
+## SELECT (columns: string)
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+/**
+ * @return T[]
+ */
+await db.select({
+  table: 'test',
+  columns: 'COUNT(*) AS total',
+});
+```
+
+> SQL Query
+
+```sql
+SELECT COUNT(*) AS total FROM test
+```
+
+<hr />
+
+## SELECT (limit: number)
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+/**
+ * @return T[]
+ */
+await db.select({
+  table: 'test',
+  limit: 10,
+});
+```
+
+> SQL Query
+
+```sql
+SELECT * FROM test LIMIT ?
+-- params: [10]
+```
+
+- By using `limit: 1`, it will return a single **row** (`T | null`).
+
+<hr />
+
+## SELECT (offset: number)
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.select({
+  table: 'test',
+  limit: 10,
+  offset: 20,
+});
+```
+
+> SQL Query
+
+```sql
+SELECT * FROM test LIMIT ? OFFSET ?
+-- params: [10, 20]
+```
+
+- By using `limit: 1`, it will return a single **row**.
+
+<hr />
+
+## SELECT (orderBy: [string, 'ASC' | 'DESC'])
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.select({
+  table: 'test',
+  orderBy: ['id'],
+  // orderBy: ['id', 'ASC'],
+  // orderBy: ['id', 'DESC'],
+});
+```
+
+> SQL Query
+
+```sql
+SELECT * FROM test ORDER BY id ASC
+```
+
+<hr />
+
+## SELECT (groupBy: string)
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.select({
+  columns: 'age, COUNT(*) AS total',
+  table: 'users',
+  groupBy: 'age',
+});
+```
+
+> SQL Query
+
+```sql
+SELECT age, COUNT(*) AS total FROM users GROUP BY age
+```
+
+<hr />
+
+## SELECT (join: JoinOptions | JoinOptions[])
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.select({
+  columns: ['users.name', 'users.age'],
+  table: 'preferences',
+  join: {
+    type: 'left',
+    table: 'users',
+    on: {
+      a: 'preferences.userId',
+      b: 'users.id',
+    },
+  },
+});
+```
+
+> SQL Query
+
+```sql
+SELECT users.name, users.age
+FROM preferences
+LEFT JOIN users ON preferences.userId = users.id
+```
+
+- You can insert multiple `JOIN` by using them within an array.
+
+<hr />
+
+## Available options
+
+```ts
+export type SelectOptions = {
+  distinct?: boolean;
+  columns?: string | string[];
+  table: string;
+  join?: JoinOptions | JoinOptions[];
+  where?: WhereClause;
+  limit?: number;
+  offset?: number;
+  groupBy?: string;
+  orderBy?: [string] | [string, 'ASC' | 'DESC'];
+  params?: unknown[];
+};
+
+export type JoinOptions = {
+  type: 'left' | 'right' | 'inner' | 'cross';
+  table: string;
+  on: {
+    a: string;
+    b: string;
+  };
+  outer?: boolean;
+};
+```
+
+<hr />
+
+## Type Assertion
+
+The `select` method provides type assertion.
+
+```ts
+import { useD1 } from 'cl-orm';
+
+// highlight-start
+const db = useD1(env.DB);
+// highlight-end
+
+interface User {
+  id: number;
+  name: string;
+}
+
+/**
+ * @return User[]
+ */
+const users = await db.select<User>({
+  table: 'test',
+});
+
+/**
+ * @return User | null
+ */
+const user = await db.select<User>({
+  table: 'test',
+  limit: 1,
+});
+```
+
+:::note
+
+The return type as `T | null` or `T[]` is determined by `limit`, not the type assertion itself:
+
+- **If no `limit` is set or it's greater than 1:** `T[]` will be returned.
+- **Setting `limit: 1`:** `T | null` will be returned.
+
+:::

package/website/docs/documentation/queries/update.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 3
+---
+
+# UPDATE
+
+> For **WHERE** examples, please see the **WHERE** section.
+
+## Simple update
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.update({
+  table: 'users',
+  set: {
+    name: 'John',
+  },
+});
+```
+
+> SQL Query
+
+```sql
+UPDATE users SET name = ?
+-- params: ['John']
+```
+
+<hr />
+
+## Update multiple columns
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+// highlight-end
+
+await db.update({
+  table: 'users',
+  set: {
+    name: 'John',
+    age: 29,
+    // highlight-start
+    // ...
+    // highlight-end
+  },
+});
+```
+
+> SQL Query
+
+```sql
+UPDATE users SET name = ?, age = ?
+-- params: ['John', 29]
+```

package/website/docs/documentation/queries/where.mdx

@@ -0,0 +1,176 @@
+---
+sidebar_position: 5
+---
+
+# WHERE Clauses
+
+The **WHERE** clause is essential for filtering records in `SELECT`, `UPDATE`, and `DELETE` operations.<br/>
+With **CL ORM**, you can use the [**OP**](/docs/category/operators) object to construct complex queries efficiently.
+
+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).<br />
+See all available operators [**here**](/docs/category/operators).
+
+> The following examples apply as well to **SELECT**, **UPDATE** and **DELETE**.
+
+## Single condition
+
+```ts
+// highlight-start
+import { OP, useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+
+await db.select({
+  table: 'users',
+  // highlight-end
+  where: OP.eq('id', 15),
+  // highlight-start
+});
+// highlight-end
+```
+
+> SQL Query
+
+```sql
+-- highlight-start
+SELECT * FROM users
+-- highlight-end
+WHERE id = ?
+
+-- params [15]
+```
+
+<hr />
+
+## Multiple conditions
+
+Ensure to use **AND**, **OR**, **XOR** or **NOT** between each condition.
+
+```ts
+// highlight-start
+import { OP, useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+
+await db.select({
+  table: 'users',
+  // highlight-end
+  where: [OP.in('id', [15, 30]), 'AND', OP.eq('status', 1)],
+  // highlight-start
+});
+// highlight-end
+```
+
+> SQL Query
+
+```sql
+-- highlight-start
+SELECT * FROM users
+-- highlight-end
+WHERE id IN (?, ?) AND status = ?
+
+-- params [15, 30, 1]
+```
+
+<hr />
+
+## Combine conditions
+
+Ensure to use **AND**, **OR**, **XOR** or **NOT** between each combination.
+
+```ts
+// highlight-start
+import { OP, useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+
+await db.select({
+  table: 'users',
+  // highlight-end
+  where: [[OP.lt('age', 18)], 'OR', [OP.eq('status', 'locked')]],
+  // highlight-start
+});
+// highlight-end
+```
+
+> SQL Query
+
+```sql
+-- highlight-start
+SELECT * FROM users
+-- highlight-end
+WHERE (age < ?) OR (status = ?)
+
+-- params [18, 'locked']
+```
+
+<hr />
+
+## Combine multiple conditions
+
+Ensure to use **AND**, **OR**, **XOR** or **NOT** between each condition and combination.
+
+```ts
+// highlight-start
+import { OP, useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+
+await db.select({
+  table: 'users',
+  // highlight-end
+  where: [
+    [OP.gte('age', 18), 'AND', OP.eq('status', 'locked')],
+    'OR',
+    [OP.lt('age', 18), 'AND', OP.eq('status', 'enabled')],
+  ],
+  // highlight-start
+});
+// highlight-end
+```
+
+> SQL Query
+
+```sql
+-- highlight-start
+SELECT * FROM users
+-- highlight-end
+WHERE (age >= ? AND status = ?) OR (age < ? AND status = ?);
+
+-- params [18, 'locked', 18, 'enabled']
+```
+
+- You can play into depth with combined conditions by encapsulating your conditions in an array. But note that this can become complex.
+
+<hr />
+
+## Manual conditions
+
+You can also use `where` as a string, creating your conditions and passing the params manually:
+
+```ts
+// highlight-start
+import { useD1 } from 'cl-orm';
+
+const db = useD1(env.DB);
+
+await db.select({
+  table: 'users',
+  // highlight-end
+  where: 'createdAt > ?',
+  params: ['2024-01-01'],
+  // highlight-start
+});
+// highlight-end
+```
+
+> SQL Query
+
+```sql
+-- highlight-start
+SELECT * FROM users
+-- highlight-end
+WHERE createdAt > ?
+
+-- params ['2024-01-01']
+```