@antelopejs/interface-database 0.1.2 → 0.1.4

package/docs/2.operations/3.table_operations.md

@@ -0,0 +1,117 @@
+# Table Operations
+
+Tables are the primary containers for documents in AQL. They are accessed through a `SchemaInstance` and provide methods for inserting, retrieving, and querying documents.
+
+## Access a Table
+
+Retrieve a table reference from a schema instance:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const db = schema.instance();
+const users = db.table("users");
+```
+
+## Type-Safe Tables
+
+Provide a generic type parameter to get type-safe operations:
+
+```typescript
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+  status: string;
+}
+
+const users = db.table<User>("users");
+
+// TypeScript now validates field names and types
+const user = await users.get("user-123"); // user is User | null
+const emails = await users.key("email");  // string[]
+```
+
+## Basic Operations
+
+### Retrieve All Documents
+
+A table reference doubles as a stream of all its documents:
+
+```typescript
+const allUsers = await users;
+console.log(`Total users: ${allUsers.length}`);
+```
+
+### Retrieve by Primary Key
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+}
+```
+
+### Retrieve by Secondary Index
+
+```typescript
+const admins = await users.getAll("admin", "role");
+```
+
+### Retrieve by Range
+
+```typescript
+const recent = await users.between(
+  "createdAt",
+  new Date("2024-01-01"),
+  new Date(),
+);
+```
+
+## Chain Operations
+
+Since `Table` extends `Selection` and `Stream`, you can chain any stream operation directly:
+
+```typescript
+// Filter and sort
+const activeByName = await users
+  .filter((u) => u.key("status").eq("active"))
+  .orderBy("name");
+
+// Paginate
+const page = await users.orderBy("createdAt").slice(0, 10);
+
+// Aggregate
+const count = await users.count();
+const avgAge = await users.avg("age");
+
+// Transform
+const names = await users.map((u) => u.key("name"));
+```
+
+## Insert Documents
+
+```typescript
+// Single document
+const ids = await users.insert({
+  name: "Alice",
+  email: "alice@example.com",
+  status: "active",
+});
+
+// Multiple documents
+const batchIds = await users.insert([
+  { name: "Bob", email: "bob@example.com", status: "active" },
+  { name: "Carol", email: "carol@example.com", status: "active" },
+]);
+
+// Upsert (update on conflict)
+await users.insert(
+  { _id: "user-123", name: "Updated" },
+  { conflict: "update" },
+);
+```
+
+For complete CRUD documentation, see [CRUD Operations](./4.crud.md).

package/docs/2.operations/4.crud.md

@@ -0,0 +1,215 @@
+# CRUD Operations
+
+CRUD operations (Create, Read, Update, Delete) form the foundation of document management in AQL. All examples assume a schema is already defined and an instance is available.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+```
+
+## Create Documents
+
+### Insert a Single Document
+
+```typescript
+const ids = await users.insert({
+  name: "Alice Johnson",
+  email: "alice@example.com",
+  status: "active",
+  createdAt: new Date(),
+});
+
+console.log("Inserted ID:", ids[0]);
+```
+
+### Insert Multiple Documents
+
+```typescript
+const ids = await users.insert([
+  { name: "Bob", email: "bob@example.com", status: "active" },
+  { name: "Carol", email: "carol@example.com", status: "active" },
+]);
+
+console.log("Inserted IDs:", ids);
+```
+
+### Upsert (Insert or Update)
+
+Use the `conflict` option to handle documents that already exist:
+
+```typescript
+// Update existing fields, keep unmentioned fields
+await users.insert(
+  { _id: "user-123", name: "Updated Name", lastSeen: new Date() },
+  { conflict: "update" },
+);
+
+// Replace the entire document
+await users.insert(
+  { _id: "user-123", name: "Replaced", email: "new@example.com" },
+  { conflict: "replace" },
+);
+```
+
+## Read Documents
+
+### Get by Primary Key
+
+```typescript
+const user = await users.get("user-123");
+
+if (user) {
+  console.log("Found:", user.name);
+} else {
+  console.log("User not found");
+}
+```
+
+### Get by Secondary Index
+
+```typescript
+const admins = await users.getAll("admin", "role");
+console.log(`Found ${admins.length} admins`);
+```
+
+### Get by Range
+
+```typescript
+const recent = await users.between(
+  "createdAt",
+  new Date("2024-01-01"),
+  new Date(),
+);
+```
+
+### Filter Documents
+
+```typescript
+// Filter with a predicate function
+const active = await users.filter((user) =>
+  user.key("status").eq("active")
+    .and(user.key("age").ge(18)),
+);
+```
+
+### Select Specific Fields
+
+```typescript
+// Keep only listed fields
+const profiles = await users.pluck("_id", "name", "avatar");
+
+// Remove sensitive fields
+const safe = await users.without("password", "ssn");
+```
+
+### Order and Paginate
+
+```typescript
+const page1 = await users.orderBy("createdAt", "desc").slice(0, 10);
+const page2 = await users.orderBy("createdAt", "desc").slice(10, 10);
+```
+
+### Stream Results
+
+For large result sets, use async iteration to process documents one at a time:
+
+```typescript
+for await (const user of users) {
+  console.log("Processing:", user.name);
+}
+```
+
+## Update Documents
+
+### Update a Single Document
+
+The `update` method modifies specified fields while preserving all other fields.
+
+```typescript
+const count = await users.get("user-123").update({
+  status: "active",
+  lastLogin: new Date(),
+});
+
+if (count === 1) {
+  console.log("User updated");
+}
+```
+
+### Update with Computed Values
+
+Pass a function to compute new values based on current ones:
+
+```typescript
+await users.get("user-123").update((user) => ({
+  loginCount: user.key("loginCount").add(1),
+  lastLogin: new Date(),
+}));
+```
+
+### Update Multiple Documents
+
+```typescript
+const count = await users
+  .getAll("inactive", "status")
+  .update({ status: "active" });
+
+console.log(`Activated ${count} users`);
+```
+
+## Replace Documents
+
+The `replace` method substitutes the entire document. Fields not included in the replacement are removed.
+
+```typescript
+const count = await users.get("user-123").replace({
+  _id: "user-123",
+  name: "Alice Updated",
+  email: "alice.new@example.com",
+  status: "active",
+  updatedAt: new Date(),
+});
+```
+
+## Delete Documents
+
+### Delete a Single Document
+
+```typescript
+const count = await users.get("user-123").delete();
+
+if (count === 1) {
+  console.log("User deleted");
+}
+```
+
+### Delete Multiple Documents
+
+```typescript
+const count = await users
+  .filter((user) => user.key("status").eq("inactive"))
+  .delete();
+
+console.log(`Deleted ${count} inactive users`);
+```
+
+## Batch Operations
+
+For large-scale inserts, batch documents to manage memory and throughput:
+
+```typescript
+const documents = Array.from({ length: 10000 }, (_, i) => ({
+  index: i,
+  value: `Item ${i}`,
+  createdAt: new Date(),
+}));
+
+const batchSize = 1000;
+for (let i = 0; i < documents.length; i += batchSize) {
+  const batch = documents.slice(i, i + batchSize);
+  await schema.instance().table("items").insert(batch);
+  console.log(`Inserted batch ${Math.floor(i / batchSize) + 1}`);
+}
+```

package/docs/2.operations/5.indexes.md

@@ -0,0 +1,110 @@
+# Index Management
+
+Indexes improve query performance by enabling the database to locate documents quickly based on indexed fields. In AQL, indexes are defined as part of the schema definition.
+
+## Define Indexes in a Schema
+
+Indexes are declared in the `indexes` property of each table definition:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = new Schema("myapp", {
+  users: {
+    fields: { name: "string", email: "string", role: "string", age: "number" },
+    indexes: {
+      email: {},                           // Simple index on the "email" field
+      role: {},                            // Simple index on the "role" field
+      name_age: { fields: ["name", "age"] }, // Compound index
+    },
+  },
+});
+```
+
+### `IndexDefinition`
+
+```typescript
+interface IndexDefinition {
+  fields?: string[];  // Fields for compound indexes (omit for single-field)
+  multi?: boolean;    // Whether this is a multi-valued index
+}
+```
+
+When `fields` is omitted, the index name is used as the field name. For compound indexes, provide the `fields` array explicitly.
+
+## Use Indexes for Queries
+
+### `getAll()` with an Index
+
+Retrieve documents by index value:
+
+```typescript
+const db = schema.instance();
+const users = db.table("users");
+
+// Query by the "role" index
+const admins = await users.getAll("admin", "role");
+
+// Query multiple values
+const targets = await users.getAll(["admin", "moderator"], "role");
+```
+
+### `between()` with an Index
+
+Retrieve documents where the index value falls within a range:
+
+```typescript
+const results = await users.between("age", 18, 65);
+```
+
+### `orderBy()` with an Index
+
+Sort results using an indexed field for better performance:
+
+```typescript
+const sorted = await users.orderBy("email", "asc");
+const newest = await users.orderBy("createdAt", "desc");
+```
+
+## Compound Indexes
+
+Compound indexes span multiple fields. Define them with the `fields` array:
+
+```typescript
+const schema = new Schema("blog", {
+  posts: {
+    fields: {
+      category: "string",
+      publishedAt: "date",
+      title: "string",
+    },
+    indexes: {
+      category_date: { fields: ["category", "publishedAt"] },
+    },
+  },
+});
+```
+
+Compound indexes support prefix-based lookups. You can query by the first field alone or by both fields together.
+
+## Multi Indexes
+
+Set `multi: true` for fields that contain arrays. The database creates an index entry for each element in the array, enabling lookups by any single element:
+
+```typescript
+const schema = new Schema("content", {
+  articles: {
+    fields: { tags: ["string"] },
+    indexes: {
+      tags: { multi: true },
+    },
+  },
+});
+```
+
+## Index Design Guidelines
+
+- **Index fields used in `getAll()` and `between()` calls** for best performance.
+- **Compound indexes** are useful when you frequently filter or sort by multiple fields together.
+- **Avoid over-indexing.** Each index adds storage overhead and slows down writes.
+- **Filter early** in your query chain to reduce the number of documents processed.

package/docs/2.operations/6.filtering.md

@@ -0,0 +1,176 @@
+# Filtering and Querying
+
+This guide covers techniques for selecting, comparing, and transforming documents using AQL's filter and ValueProxy capabilities.
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const users = schema.instance().table("users");
+```
+
+## Basic Filtering
+
+Use the `filter` method with a predicate function. The callback receives a `ValueProxy<T>` representing each document.
+
+```typescript
+const active = await users.filter((user) =>
+  user.key("status").eq("active"),
+);
+```
+
+## Comparison Operators
+
+### Equality and Inequality
+
+```typescript
+const admins = await users.filter((u) => u.key("role").eq("admin"));
+const nonAdmins = await users.filter((u) => u.key("role").ne("admin"));
+```
+
+### Numeric Comparisons
+
+```typescript
+const adults = await users.filter((u) => u.key("age").ge(18));
+const seniors = await users.filter((u) => u.key("age").gt(65));
+const young = await users.filter((u) => u.key("age").lt(18));
+const discounted = await users.filter((u) => u.key("age").le(25));
+```
+
+## Logical Operators
+
+Combine conditions with `and()`, `or()`, and `not()`:
+
+```typescript
+// AND
+const verified = await users.filter((u) =>
+  u.key("status").eq("active").and(u.key("emailVerified").eq(true)),
+);
+
+// OR
+const important = await users.filter((u) =>
+  u.key("role").eq("admin").or(u.key("plan").eq("premium")),
+);
+
+// NOT
+const standard = await users.filter((u) =>
+  u.key("plan").eq("premium").not(),
+);
+
+// Complex combinations
+const target = await users.filter((u) =>
+  u.key("status").eq("active")
+    .and(
+      u.key("plan").eq("premium")
+        .or(u.key("totalPurchases").gt(500)),
+    ),
+);
+```
+
+## String Operations
+
+```typescript
+// Case-insensitive match
+const bobs = await users.filter((u) =>
+  u.key("name").downcase().eq("bob"),
+);
+
+// Regex matching
+const gmailUsers = await users.filter((u) =>
+  u.key("email").match("@gmail\\.com$"),
+);
+
+// String concatenation in filter
+const fullNameMatch = await users.filter((u) =>
+  u.key("firstName").concat(u.key("lastName")).eq("JohnSmith"),
+);
+```
+
+## Date Filtering
+
+### Date Comparisons
+
+```typescript
+const newUsers = await users.filter((u) =>
+  u.key("createdAt").gt(new Date("2024-01-01")),
+);
+
+const q1Users = await users.filter((u) =>
+  u.key("createdAt").ge(new Date("2024-01-01"))
+    .and(u.key("createdAt").lt(new Date("2024-04-01"))),
+);
+```
+
+### Date Components
+
+```typescript
+const thisYear = await users.filter((u) =>
+  u.key("createdAt").year().eq(2024),
+);
+
+const morningLogins = await users.filter((u) =>
+  u.key("lastLogin").hours().lt(12),
+);
+```
+
+## Array Operations
+
+```typescript
+// Check array contents
+const jsPosts = await schema.instance().table("posts").filter((post) =>
+  post.key("tags").includes("javascript"),
+);
+
+// Check array length
+const wellTagged = await schema.instance().table("posts").filter((post) =>
+  post.key("tags").count().gt(3),
+);
+
+// Check if empty
+const untagged = await schema.instance().table("posts").filter((post) =>
+  post.key("tags").isempty(),
+);
+```
+
+## Default Values in Filters
+
+Use `default()` to handle potentially null fields:
+
+```typescript
+const activeUsers = await users.filter((u) =>
+  u.key("active").default(false).eq(true),
+);
+
+const frequentVisitors = await users.filter((u) =>
+  u.key("visits").default(0).gt(10),
+);
+```
+
+## Ordering and Pagination
+
+```typescript
+// Sort ascending
+const byName = await users.orderBy("name", "asc");
+
+// Sort descending
+const newest = await users.orderBy("createdAt", "desc");
+
+// Paginate
+const page1 = await users.orderBy("createdAt").slice(0, 10);
+const page2 = await users.orderBy("createdAt").slice(10, 10);
+```
+
+## Performance Tips
+
+1. **Use `getAll()` and `between()` with indexes** instead of `filter()` when possible. Index-based lookups are significantly faster than full scans.
+2. **Filter early** in the query chain to reduce the dataset before applying transformations or aggregations.
+3. **Limit result sets** with `slice()` to avoid transferring unnecessary data.
+4. **Avoid complex computations** inside filter predicates when simpler alternatives exist.
+
+```typescript
+// Slower: full table scan with filter
+const slow = await users.filter((u) => u.key("email").eq("user@example.com"));
+
+// Faster: index-based lookup
+const fast = await users.getAll("user@example.com", "email");
+```