alsabase 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# AlsaBase JavaScript / TypeScript Client SDK
+
+Official client SDK for **AlsaBase** - lightweight, batteries-included SQLite backend engine with instant REST APIs, realtime subscriptions, authentication, and superuser collection management.
+
+---
+
+## Installation
+
+```bash
+npm install alsabase
+```
+
+Or via yarn/pnpm:
+```bash
+yarn add alsabase
+# or
+pnpm add alsabase
+```
+
+Browser via CDN (ESM):
+```html
+<script type="module">
+  import AlsaBase from "https://cdn.jsdelivr.net/npm/alsabase/dist/index.js";
+
+  const ab = new AlsaBase("http://127.0.0.1:8090");
+</script>
+```
+
+---
+
+## Quickstart
+
+```typescript
+import AlsaBase from "alsabase";
+
+const ab = new AlsaBase("http://127.0.0.1:8090");
+
+// 1. Authenticate as a regular user
+const authData = await ab.collection("users").authWithPassword("john@example.com", "12345678");
+
+// 2. Query paginated records
+const result = await ab.collection("posts").getList(1, 20, {
+  filter: ab.filter("status = {:status}", { status: "published" }),
+  sort: "-created_at",
+});
+
+console.log(result.items);
+
+// 3. Create a new record
+const newPost = await ab.collection("posts").create({
+  title: "Hello World",
+  content: "Welcome to AlsaBase!",
+  status: "published",
+});
+
+// 4. Realtime subscription
+const unsubscribe = await ab.collection("posts").subscribe("*", (e) => {
+  console.log("Post event:", e.action, e.record);
+});
+```
+
+---
+
+## Core Features
+
+### 1. Authentication
+
+#### User Authentication (Password & OTP)
+```typescript
+// Login with username or email
+await ab.collection("users").authWithPassword("test@example.com", "password123");
+
+// One-Time Password (OTP)
+await ab.collection("users").requestOTP("test@example.com");
+await ab.collection("users").authWithOTP("123456", "test@example.com");
+
+// Check current auth status
+console.log(ab.authStore.isValid);
+console.log(ab.authStore.token);
+console.log(ab.authStore.model);
+
+// Logout
+ab.authStore.clear();
+```
+
+#### Superuser / Admin Authentication
+```typescript
+// Login as Superuser / Admin
+await ab.superusers.authWithPassword("admin@example.com", "superpassword");
+
+// Admin alias is also available:
+await ab.admins.authWithPassword("admin@example.com", "superpassword");
+
+// Check if initial superuser setup is required
+const { hasSuperuser } = await ab.superusers.hasInitialSuperuser();
+
+if (!hasSuperuser) {
+  await ab.superusers.setupInitialSuperuser("admin@example.com", "superpassword");
+}
+```
+
+---
+
+### 2. Record Operations (CRUD)
+
+```typescript
+// List records with pagination
+const list = await ab.collection("articles").getList(1, 50, {
+  filter: 'status = "published"',
+  sort: "-created_at",
+});
+
+// Fetch all records across pages
+const allArticles = await ab.collection("articles").getFullList();
+
+// Fetch single record by ID
+const article = await ab.collection("articles").getOne("RECORD_ID");
+
+// Fetch first item matching filter
+const first = await ab.collection("articles").getFirstListItem('slug = "intro"');
+
+// Create record
+const record = await ab.collection("articles").create({
+  title: "New Post",
+  slug: "new-post",
+});
+
+// Update record
+await ab.collection("articles").update("RECORD_ID", {
+  title: "Updated Title",
+});
+
+// Delete record
+await ab.collection("articles").delete("RECORD_ID");
+
+// Truncate (delete all records - Superuser only)
+await ab.collection("articles").truncate();
+```
+
+---
+
+### 3. Collection Management (Superuser / Admin)
+
+Create, inspect, and update collection schemas dynamically from code:
+
+```typescript
+// 1. Inspect table schema via ab.collection()
+const tableSchema = await ab.collection("products").getSchema();
+console.log("Table columns:", tableSchema.fields);
+
+// 2. Inspect table schema via ab.collections service
+const col = await ab.collections.getSchema("products"); // or ab.collections.getOne("products")
+
+// 3. Inspect table schema via top-level helper
+const schema = await ab.getSchema("products");
+
+// List all collections
+const collections = await ab.collections.getFullList();
+
+// Create a new collection
+const newCollection = await ab.collections.create({
+  name: "products",
+  type: "base",
+  fields: [
+    { name: "title", type: "text", required: true },
+    { name: "price", type: "number", required: true },
+    { name: "in_stock", type: "bool" },
+    { name: "tags", type: "json" },
+  ],
+  rules: {
+    listRule: "", // Public
+    viewRule: "", // Public
+    createRule: "@request.auth.id != ''", // Authenticated users
+    updateRule: "@request.auth.id != ''",
+    deleteRule: null, // Admin only
+  },
+});
+
+// Update collection schema or rules
+await ab.collections.update("products", {
+  fields: [
+    ...newCollection.fields,
+    { name: "sku", type: "text", unique: true },
+  ],
+});
+
+// Delete collection
+await ab.collections.delete("products");
+```
+
+---
+
+### 4. Server Logs & Telemetry (Superuser / Admin)
+
+Query server error logs, execution metrics, and latency timelines:
+
+```typescript
+// Query recent server logs
+const logs = await ab.logs.getList(1, 50, {
+  level: "ERROR",
+  search: "/api/collections",
+});
+
+// Get log summary stats
+const stats = await ab.logs.getStats();
+console.log("Total errors:", stats.error, "Average latency:", stats.avgDurationMs, "ms");
+
+// Get 7-day hourly request timeline
+const timeline = await ab.logs.getTimeline();
+
+// Clear logs
+await ab.logs.clear();
+```
+
+---
+
+### 5. Realtime Subscriptions
+
+Subscribe to realtime create, update, and delete events via WebSocket / SSE:
+
+```typescript
+// Subscribe to all changes in a collection
+const unsub = await ab.collection("messages").subscribe("*", (e) => {
+  console.log("Action:", e.action); // 'create' | 'update' | 'delete'
+  console.log("Record:", e.record);
+});
+
+// Subscribe to a specific record
+const unsubRecord = await ab.collection("messages").subscribe("RECORD_ID", (e) => {
+  console.log("Message updated:", e.record);
+});
+
+// Unsubscribe
+unsub();
+```
+
+---
+
+### 6. File Asset Helpers
+
+Generate URLs for uploaded media files and static site assets:
+
+```typescript
+// Record file URL helper
+const fileUrl = ab.files.getUrl(record, record.avatar);
+
+// Public website assets helper (served from _public)
+const publicUrl = ab.files.getPublicUrl("images/hero.webp");
+```
+
+---
+
+### 7. Serverless Hooks & Crons (Superuser / Admin)
+
+Inspect and trigger serverless backend hooks:
+
+```typescript
+// Get overview of loaded hook files, registered routes, and cron jobs
+const overview = await ab.hooks.getOverview();
+
+// Manually trigger a scheduled cron job
+await ab.hooks.triggerCron("daily_cleanup");
+
+// Reload hooks
+await ab.hooks.reload();
+```
+
+---
+
+## License
+
+MIT License.

package/dist/Client.d.ts

@@ -0,0 +1,60 @@
+import { BaseAuthStore } from "./stores/BaseAuthStore";
+import { RecordService } from "./services/RecordService";
+import { CollectionService } from "./services/CollectionService";
+import { SuperuserService } from "./services/SuperuserService";
+import { LogService } from "./services/LogService";
+import { RealtimeService } from "./services/RealtimeService";
+import { FileService } from "./services/FileService";
+import { HooksService } from "./services/HooksService";
+import type { SendOptions, RecordModel, CollectionModel, CommonOptions } from "./types";
+export declare class AlsaBase {
+    baseUrl: string;
+    authStore: BaseAuthStore;
+    readonly superusers: SuperuserService;
+    readonly collections: CollectionService;
+    readonly logs: LogService;
+    readonly realtime: RealtimeService;
+    readonly files: FileService;
+    readonly hooks: HooksService;
+    private recordServices;
+    private cancelControllers;
+    constructor(baseUrl?: string, authStore?: BaseAuthStore);
+    /**
+     * Alias for superusers service (admins)
+     */
+    get admins(): SuperuserService;
+    /**
+     * Returns a RecordService instance for the specified collection
+     */
+    collection<T = RecordModel>(idOrName: string): RecordService<T>;
+    /**
+     * Returns the schema and column definitions for a table/collection (Requires Superuser authentication)
+     */
+    getSchema(idOrName: string, options?: CommonOptions): Promise<CollectionModel>;
+    /**
+     * Returns the schema and column definitions for a table/collection (Requires Superuser authentication)
+     * Alias for getSchema()
+     */
+    getTableSchema(idOrName: string, options?: CommonOptions): Promise<CollectionModel>;
+    /**
+     * Helper to format filter expression string with parameterized values
+     */
+    filter(expr: string, params?: Record<string, any>): string;
+    /**
+     * Cancels a pending request with matching requestKey
+     */
+    cancelRequest(requestKey: string): this;
+    /**
+     * Cancels all pending requests
+     */
+    cancelAllRequests(): this;
+    /**
+     * Builds an absolute URL with query parameters
+     */
+    buildUrl(path: string, query?: Record<string, any>): string;
+    /**
+     * Dispatches an HTTP request to the AlsaBase server
+     */
+    send<T = any>(path: string, options?: SendOptions): Promise<T>;
+}
+export type Client = AlsaBase;

package/dist/Client.js

@@ -0,0 +1,220 @@
+import { BaseAuthStore } from "./stores/BaseAuthStore";
+import { LocalAuthStore } from "./stores/LocalAuthStore";
+import { ClientResponseError } from "./ClientResponseError";
+import { RecordService } from "./services/RecordService";
+import { CollectionService } from "./services/CollectionService";
+import { SuperuserService } from "./services/SuperuserService";
+import { LogService } from "./services/LogService";
+import { RealtimeService } from "./services/RealtimeService";
+import { FileService } from "./services/FileService";
+import { HooksService } from "./services/HooksService";
+export class AlsaBase {
+    baseUrl;
+    authStore;
+    superusers;
+    collections;
+    logs;
+    realtime;
+    files;
+    hooks;
+    recordServices = new Map();
+    cancelControllers = new Map();
+    constructor(baseUrl = "/", authStore) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.authStore =
+            authStore ||
+                (typeof window !== "undefined" ? new LocalAuthStore() : new BaseAuthStore());
+        this.superusers = new SuperuserService(this);
+        this.collections = new CollectionService(this);
+        this.logs = new LogService(this);
+        this.realtime = new RealtimeService(this);
+        this.files = new FileService(this);
+        this.hooks = new HooksService(this);
+    }
+    /**
+     * Alias for superusers service (admins)
+     */
+    get admins() {
+        return this.superusers;
+    }
+    /**
+     * Returns a RecordService instance for the specified collection
+     */
+    collection(idOrName) {
+        if (!this.recordServices.has(idOrName)) {
+            this.recordServices.set(idOrName, new RecordService(this, idOrName));
+        }
+        return this.recordServices.get(idOrName);
+    }
+    /**
+     * Returns the schema and column definitions for a table/collection (Requires Superuser authentication)
+     */
+    async getSchema(idOrName, options) {
+        return this.collections.getOne(idOrName, options);
+    }
+    /**
+     * Returns the schema and column definitions for a table/collection (Requires Superuser authentication)
+     * Alias for getSchema()
+     */
+    async getTableSchema(idOrName, options) {
+        return this.collections.getOne(idOrName, options);
+    }
+    /**
+     * Helper to format filter expression string with parameterized values
+     */
+    filter(expr, params = {}) {
+        if (!params || Object.keys(params).length === 0) {
+            return expr;
+        }
+        let result = expr;
+        for (const [key, val] of Object.entries(params)) {
+            let formattedVal;
+            if (val === null || val === undefined) {
+                formattedVal = "null";
+            }
+            else if (typeof val === "number" || typeof val === "boolean") {
+                formattedVal = String(val);
+            }
+            else if (val instanceof Date) {
+                formattedVal = `"${val.toISOString()}"`;
+            }
+            else {
+                formattedVal = `"${String(val).replace(/"/g, '\\"')}"`;
+            }
+            const pattern = new RegExp(`{:?\\b${key}\\b}`, "g");
+            result = result.replace(pattern, formattedVal);
+        }
+        return result;
+    }
+    /**
+     * Cancels a pending request with matching requestKey
+     */
+    cancelRequest(requestKey) {
+        const controller = this.cancelControllers.get(requestKey);
+        if (controller) {
+            controller.abort();
+            this.cancelControllers.delete(requestKey);
+        }
+        return this;
+    }
+    /**
+     * Cancels all pending requests
+     */
+    cancelAllRequests() {
+        for (const controller of this.cancelControllers.values()) {
+            controller.abort();
+        }
+        this.cancelControllers.clear();
+        return this;
+    }
+    /**
+     * Builds an absolute URL with query parameters
+     */
+    buildUrl(path, query) {
+        const cleanPath = path.startsWith("/") ? path : `/${path}`;
+        let url = `${this.baseUrl}${cleanPath}`;
+        if (query && Object.keys(query).length > 0) {
+            const searchParams = new URLSearchParams();
+            for (const [k, v] of Object.entries(query)) {
+                if (v !== undefined && v !== null && v !== "") {
+                    searchParams.append(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+                }
+            }
+            const qs = searchParams.toString();
+            if (qs) {
+                url += (url.includes("?") ? "&" : "?") + qs;
+            }
+        }
+        return url;
+    }
+    /**
+     * Dispatches an HTTP request to the AlsaBase server
+     */
+    async send(path, options = {}) {
+        const url = this.buildUrl(path, options.query || options.params);
+        // Auto-cancellation handling
+        let requestKey = options.requestKey;
+        if (requestKey === undefined && options.autoCancel !== false && (options.method === "GET" || !options.method)) {
+            requestKey = `${options.method || "GET"} ${url}`;
+        }
+        let controller;
+        if (requestKey) {
+            this.cancelRequest(requestKey);
+            controller = new AbortController();
+            this.cancelControllers.set(requestKey, controller);
+        }
+        const headers = {
+            ...(options.headers || {}),
+        };
+        // Attach Authorization header if authenticated and not already provided
+        if (!headers["Authorization"] && !headers["authorization"] && this.authStore.token) {
+            headers["Authorization"] = `Bearer ${this.authStore.token}`;
+        }
+        let body = options.body;
+        // Auto stringify plain objects if not FormData/Blob/Buffer
+        if (body !== undefined &&
+            body !== null &&
+            typeof body === "object" &&
+            typeof body.append !== "function" &&
+            !(typeof Blob !== "undefined" && body instanceof Blob) &&
+            !(typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer)) {
+            if (!headers["Content-Type"] && !headers["content-type"]) {
+                headers["Content-Type"] = "application/json";
+            }
+            body = JSON.stringify(body);
+        }
+        const fetchOptions = {
+            ...options,
+            headers,
+            body,
+            signal: controller ? controller.signal : options.signal,
+        };
+        try {
+            const response = await fetch(url, fetchOptions);
+            if (requestKey) {
+                this.cancelControllers.delete(requestKey);
+            }
+            // Parse response JSON or text
+            let data = null;
+            const contentType = response.headers.get("content-type") || "";
+            if (contentType.includes("application/json")) {
+                data = await response.json().catch(() => null);
+            }
+            else {
+                data = await response.text().catch(() => null);
+            }
+            if (!response.ok) {
+                throw new ClientResponseError({
+                    url,
+                    status: response.status,
+                    data,
+                    response,
+                });
+            }
+            return data;
+        }
+        catch (err) {
+            if (requestKey) {
+                this.cancelControllers.delete(requestKey);
+            }
+            if (err.name === "AbortError") {
+                throw new ClientResponseError({
+                    url,
+                    status: 0,
+                    data: { message: "The request was autocancelled or aborted." },
+                    isAbort: true,
+                    originalError: err,
+                });
+            }
+            if (err instanceof ClientResponseError) {
+                throw err;
+            }
+            throw new ClientResponseError({
+                url,
+                status: 0,
+                data: { message: err.message },
+                originalError: err,
+            });
+        }
+    }
+}

package/dist/ClientResponseError.d.ts

@@ -0,0 +1,25 @@
+export declare class ClientResponseError extends Error {
+    url: string;
+    status: number;
+    response: {
+        [key: string]: any;
+    };
+    data: {
+        [key: string]: any;
+    };
+    isAbort: boolean;
+    originalError: any;
+    constructor(errData?: any);
+    toJSON(): {
+        url: string;
+        status: number;
+        data: {
+            [key: string]: any;
+        };
+        response: {
+            [key: string]: any;
+        };
+        isAbort: boolean;
+        message: string;
+    };
+}

package/dist/ClientResponseError.js

@@ -0,0 +1,46 @@
+export class ClientResponseError extends Error {
+    url = "";
+    status = 0;
+    response = {};
+    data = {};
+    isAbort = false;
+    originalError = null;
+    constructor(errData) {
+        super("ClientResponseError");
+        if (errData !== null && typeof errData === "object") {
+            this.url = errData.url || "";
+            this.status = errData.status || 0;
+            this.data = errData.data || {};
+            this.response = errData.response || this.data;
+            this.isAbort = !!errData.isAbort;
+            this.originalError = errData.originalError || null;
+            if (errData.message) {
+                this.message = errData.message;
+            }
+            else if (this.data?.message) {
+                this.message = this.data.message;
+            }
+            else if (this.data?.error) {
+                this.message = this.data.error;
+            }
+            else if (this.status) {
+                this.message = `Response error. Status code: ${this.status}`;
+            }
+        }
+        if (typeof DOMException !== "undefined" && errData instanceof DOMException && errData.name === "AbortError") {
+            this.isAbort = true;
+            this.message = "The request was autocancelled or aborted.";
+        }
+        Object.setPrototypeOf(this, ClientResponseError.prototype);
+    }
+    toJSON() {
+        return {
+            url: this.url,
+            status: this.status,
+            data: this.data,
+            response: this.response,
+            isAbort: this.isAbort,
+            message: this.message,
+        };
+    }
+}