@docstack/client 0.0.1

package/README.md

@@ -0,0 +1,214 @@
+[![Donate](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate/?hosted_button_id=4QSQ8L9AK2C74)
+
+
+# @docstack/client
+
+**The Intelligent, Offline-First Database Engine for Modern Web Apps.**
+
+DocStack Client is a standalone, browser-based datastore built on PouchDB. It bridges the gap between simple client-side storage and full-fledged backend databases by bringing schemas, relationships, SQL-like querying, and background processing directly to the browser.
+
+It is designed for applications that require **offline capabilities**, **strong data consistency**, and **secure local storage**, all while sharing the same powerful data model as the DocStack server.
+
+## 🚀 Why DocStack?
+
+### Business Advantages
+
+- **Logic as Data**: Store business rules, validation scripts, and background jobs as documents in the database. Update your application's behavior dynamically without redeploying the entire codebase.
+- **Zero-Latency UX**: By running the database locally, your UI updates instantly. Data syncs to the server in the background when a connection is available.
+- **Enterprise-Grade Security**: Built-in field-level encryption ensures that sensitive user data (PII, health records) is encrypted *before* it hits the disk, protecting it even if the device is compromised.
+
+### Technical Highlights
+
+- **Structured NoSQL**: Enjoy the flexibility of JSON documents with the rigor of strict schemas (powered by Zod).
+- **SQL in the Browser**: Stop writing complex map/reduce functions. Query your local data using standard SQL syntax, including `JOIN`s, `UNION`s, and aggregations.
+- **Reactive Architecture**: Subscribe to changes on specific classes or documents to update your UI in real-time.
+- **Background Jobs**: Offload heavy processing (data cleanup, report generation) to background workers that run independently of the UI thread.
+
+## 📦 Installation
+
+To add the client to your project, use your preferred package manager.
+
+```bash
+npm install @docstack/client
+```
+
+## ⚡ Quick Start
+
+Initialize the stack and create your first data model.
+
+```typescript
+import { ClientStack, Class, Attribute } from '@docstack/client';
+
+// 1. Initialize the stack (creates a local PouchDB instance)
+const stack = await ClientStack.create('my-app-db');
+
+// 2. Define a 'Task' class
+const taskClass = await Class.create(stack, 'Task', 'class', 'User Tasks');
+
+// 3. Add attributes to the schema
+await Attribute.create(taskClass, 'title', 'string', 'Task Title', { mandatory: true });
+await Attribute.create(taskClass, 'isComplete', 'boolean', 'Done?', { defaultValue: false });
+
+// 4. Create a document
+const myTask = await taskClass.add({
+    title: 'Install DocStack',
+    isComplete: true
+});
+
+console.log('Created Task:', myTask);
+```
+
+## 📚 Core Features & Usage
+
+### 1. Advanced Querying (SQL-like)
+
+DocStack includes a powerful query engine that translates SQL into optimized PouchDB selectors and in-memory operations.
+
+```typescript
+// Find all high-priority tasks, join with Assignee, and sort
+const { rows } = await stack.query(`
+    SELECT t.title, u.username AS assignee
+    FROM Task AS t
+    JOIN User AS u ON u._id = t.assigneeId
+    WHERE t.priority = 'high' AND t.isComplete = false
+    ORDER BY t.createdAt DESC
+`);
+```
+
+### 2. Relationships & Domains
+
+In addition to foreign keys, define strict relationships between data types using Domains.
+
+```typescript
+import { Domain } from '@docstack/client';
+
+// Define a 1:N relationship between Projects and Tasks
+const domain = await Domain.create(
+    stack,
+    null,
+    'ProjectTasks',
+    'domain',
+    '1:N',
+    projectClass,
+    taskClass
+);
+
+// Now you can traverse relationships easily or enforce referential integrity.
+```
+
+### 3. Background Jobs
+
+Define executable logic stored in the database. Jobs run in a sandboxed environment and can be triggered manually or by system events.
+
+```typescript
+// Define a job that archives old tasks
+const archiveJob = {
+    _id: 'Job-ArchiveOldTasks',
+    '~class': '~Job',
+    name: 'Archive Tasks',
+    type: 'user',
+    workerPlatform: 'client',
+    isEnabled: true,
+    content: `
+        async function execute(stack, params) {
+            const { rows } = await stack.query("SELECT _id FROM Task WHERE isComplete = true");
+            for (const row of rows) {
+                // Custom logic to move task to archive...
+                console.log('Archiving:', row._id);
+            }
+            return { metadata: { archivedCount: rows.length } };
+        }
+    `
+};
+
+// Save the job definition
+await stack.db.bulkDocs([archiveJob]);
+
+// Execute it
+const run = await stack.jobEngine.executeJob('Job-ArchiveOldTasks');
+console.log('Job Status:', run.status);
+```
+
+### 4. Triggers
+
+Define custom data validations and transformations that execute automatically before or after document operations. Trigger logic is stored as data and hydrated at runtime.
+
+```typescript
+// This trigger automatically generates a URL-friendly slug from a document's title
+const generateSlugTrigger = {
+    name: 'generate-slug-from-title',
+    order: 'before',
+    run: `document.slug = document.title.toLowerCase().replace(/\\s+/g, '-'); return document;`
+};
+
+// Add the trigger to a class schema
+await blogPostClass.addTrigger(generateSlugTrigger);
+
+// Now when you save a BlogPost, the slug is generated automatically
+const post = await blogPostClass.add({ title: 'Hello World' });
+console.log(post.slug); // 'hello-world'
+```
+
+### 5. Access Policies
+
+Control who can read or write data with granular, rule-based policies. Great for implementing role-based access control (RBAC) and multi-tenant applications.
+
+```typescript
+// Policy: Only users in the 'editors' group can write to Article documents
+const editorsOnlyWritePolicy = {
+    _id: 'Policy-Article-EditorsWrite',
+    '~class': '~Policy',
+    targetClass: ['Class-Article'],
+    groupId: 'Group-Editors',
+    rule: `
+        // 'session' and 'document' are injected at runtime
+        return session && session.sessionStatus === 'active';
+    `
+};
+
+// Policy: Published articles are readable by anyone
+const publicReadPolicy = {
+    _id: 'Policy-Article-PublicRead',
+    '~class': '~Policy',
+    targetClass: ['Class-Article'],
+    rule: `
+        if (document.status === 'published') {
+            return true;
+        }
+    `
+};
+
+// Save policies to activate them
+await stack.db.bulkDocs([editorsOnlyWritePolicy, publicReadPolicy]);
+```
+
+### 6. Security & Encryption
+
+Protect sensitive data transparently.
+
+```typescript
+// Define a class with an encrypted field
+await Attribute.create(userClass, 'socialSecurityNumber', 'string', 'SSN', {
+    encrypted: true
+});
+
+// When you save a document, 'socialSecurityNumber' is encrypted using a document secure key.
+// It is stored as ciphertext in PouchDB and only decrypted when accessed via the API.
+```
+
+## 🧩 Architecture
+
+DocStack Client is composed of several modular engines:
+
+| Engine | Description |
+|--------|-------------|
+| **Core DB** | PouchDB for storage and sync |
+| **Schema Engine** | Zod-based validation and schema hydration |
+| **Query Engine** | SQL parser and planner for complex data retrieval |
+| **Job Engine** | Manages asynchronous tasks and background workers |
+| **Crypto Engine** | Handles key derivation (PBKDF2) and AES-GCM encryption |
+| **Policy Engine** | Enforces granular read/write access rules per class or user-targeted, based on user sessions and document's content |
+
+---
+
+Built with ❤️ for the modern web.

package/lib/core/attribute.d.ts

@@ -0,0 +1,174 @@
+import z, { ZodType } from "zod";
+import Class from "./class.js";
+import { Attribute as Attribute_, AttributeModel, AttributeType, AttributeTypeConfig } from "@docstack/shared";
+/**
+ * Represents a single attribute (field) within a Class schema.
+ *
+ * Attributes define the structure of documents, including their type,
+ * validation rules (via Zod), and configuration options like mandatory,
+ * default values, primary keys, and foreign key references.
+ *
+ * Use the static factory method {@link Attribute.create} to instantiate
+ * attributes with proper validation and persistence.
+ *
+ * @example
+ * ```typescript
+ * // Create a string attribute
+ * const titleAttr = await Attribute.create(taskClass, 'title', 'string', 'Task Title', {
+ *     mandatory: true,
+ *     maxLength: 200
+ * });
+ *
+ * // Create a foreign key reference
+ * const assigneeAttr = await Attribute.create(taskClass, 'assigneeId', 'foreign_key', 'Assigned User', {
+ *     targetClass: 'User'
+ * });
+ * ```
+ *
+ * @extends Attribute_
+ */
+declare class Attribute extends Attribute_ {
+    /** The attribute name used as the document field key. */
+    name: string;
+    /** Optional description explaining the attribute's purpose. */
+    description?: string;
+    /** The underlying AttributeModel containing type and configuration. */
+    model: AttributeModel;
+    /** Zod schema for runtime validation of this field. */
+    field: ZodType;
+    /** Reference to the parent Class that owns this attribute. */
+    class: Class | null;
+    /** Default value to use when the field is not provided. */
+    defaultValue?: any;
+    /**
+     * Creates a new Attribute instance.
+     * For most use cases, prefer using {@link Attribute.create} which also persists the attribute.
+     *
+     * @param classObj - The parent Class for this attribute
+     * @param name - The attribute name
+     * @param type - The attribute type (e.g., 'string', 'integer', 'boolean', 'enum')
+     * @param description - Optional description
+     * @param config - Type-specific configuration options
+     */
+    constructor(classObj: Class | null, name: string, type: AttributeType["type"], description?: string, config?: AttributeType["config"]);
+    /**
+     * Validates that reference-type attributes have proper domain configuration.
+     * Called automatically during {@link Attribute.create}.
+     * @throws Error if the reference configuration is invalid
+     */
+    ensureReferenceConfigIsValid: () => Promise<void>;
+    /**
+     * Builds the Zod validation schema based on attribute type and configuration.
+     * Called automatically during construction.
+     */
+    setField: () => void;
+    /**
+     * Creates a new Attribute and persists it to the parent Class.
+     * This is the primary factory method for creating attributes.
+     *
+     * @param classObj - The parent Class to add the attribute to
+     * @param name - The attribute name
+     * @param type - The attribute type
+     * @param description - Optional description
+     * @param config - Type-specific configuration
+     * @returns The created Attribute instance
+     *
+     * @example
+     * ```typescript
+     * const priceAttr = await Attribute.create(productClass, 'price', 'decimal', 'Product price', {
+     *     min: 0,
+     *     precision: 2,
+     *     mandatory: true
+     * });
+     * ```
+     */
+    static create(classObj: Class, name: string, type: AttributeType["type"], description?: string, config?: AttributeType["config"]): Promise<Attribute>;
+    /**
+     * Checks if this attribute is marked as a primary key.
+     * @returns `true` if this is a primary key attribute
+     */
+    isPrimaryKey: () => boolean;
+    /**
+     * Checks if this attribute is mandatory (required).
+     * @returns `true` if the attribute is mandatory
+     */
+    isMandatory: () => boolean;
+    /**
+     * Returns the AttributeModel for this attribute.
+     * @returns The underlying AttributeModel
+     */
+    getModel: () => AttributeModel;
+    /**
+     * Returns the parent Class for this attribute.
+     * @returns The Class instance
+     * @throws Error if the attribute has no parent class
+     */
+    getClass: () => Class;
+    /**
+     * Validates a value against this attribute's Zod schema.
+     *
+     * @param data - The value to validate
+     * @returns Zod safe parse result with success status and data/error
+     *
+     * @example
+     * ```typescript
+     * const result = await priceAttr.validate(19.99);
+     * if (result.success) {
+     *     console.log('Valid:', result.data);
+     * } else {
+     *     console.log('Invalid:', result.error);
+     * }
+     * ```
+     */
+    validate: (data: any) => Promise<z.ZodSafeParseResult<unknown>>;
+    /**
+     * Adds an attribute to its parent class and persists to the database.
+     * Used internally by {@link Attribute.create}.
+     *
+     * @param attributeObj - The Attribute instance to build
+     * @returns The Attribute instance
+     * @throws Error if the class has no stack connection
+     */
+    static build: (attributeObj: Attribute) => Promise<Attribute>;
+    setModel: (model: AttributeModel) => void;
+    getType: (type: AttributeType["type"]) => "string" | "boolean" | "object" | "integer" | "date" | "decimal" | "foreign_key" | "enum" | "reference";
+    /**
+     * Returns an empty/default value for this attribute.
+     * Uses the Zod schema's default value if configured.
+     * @returns Object with attribute name as key and default/null value
+     */
+    getEmpty: () => {
+        [x: string]: unknown;
+    };
+    /**
+     * Returns the attribute name.
+     * @returns The attribute name string
+     */
+    getName: () => string;
+    checkTypeValidity: (type: string) => boolean;
+    getTypeConf: (type: AttributeType["type"], config: AttributeType["config"] | undefined) => AttributeTypeConfig | ({
+        maxLength?: number;
+        defaultValue?: string;
+    } & AttributeTypeConfig) | ({
+        max?: number;
+        min?: number;
+        defaultValue?: number;
+    } & AttributeTypeConfig) | ({
+        format?: string;
+        defaultValue?: string | number;
+        max?: string | number;
+        min?: string | number;
+    } & AttributeTypeConfig) | ({
+        max?: number;
+        min?: number;
+        precision?: number;
+        defaultValue?: number;
+    } & AttributeTypeConfig) | ({
+        defaultValue?: boolean;
+    } & AttributeTypeConfig) | ({
+        targetClass?: string;
+    } & AttributeTypeConfig) | ({
+        domain: string;
+    } & AttributeTypeConfig);
+}
+export default Attribute;

package/lib/core/attribute.js

@@ -0,0 +1,296 @@
+var _a;
+import z from "zod";
+import { Attribute as Attribute_, ATTRIBUTE_TYPES } from "@docstack/shared";
+class Attribute extends Attribute_ {
+    constructor(classObj = null, name, type, description, config) {
+        super(classObj, name, type, config);
+        this.field = z.any();
+        this.ensureReferenceConfigIsValid = async () => {
+            if (this.model.type !== "reference") {
+                return;
+            }
+            if (!this.class) {
+                throw new Error(`Attribute '${this.name}' must belong to a class to validate reference configuration.`);
+            }
+            const stack = this.class.getStack();
+            if (!stack) {
+                throw new Error(`Class '${this.class.getName()}' is not attached to a stack.`);
+            }
+            const config = this.model.config;
+            const domainName = config.domain;
+            if (typeof domainName !== "string" || domainName.length === 0) {
+                throw new Error(`Attribute '${this.name}' of type 'reference' must declare a domain.`);
+            }
+            if (config.isArray) {
+                throw new Error(`Attribute '${this.name}' of type 'reference' cannot be an array.`);
+            }
+            const domain = await stack.getDomain(domainName);
+            if (!domain) {
+                throw new Error(`Domain '${domainName}' was not found for attribute '${this.name}'.`);
+            }
+            const classId = this.class.id;
+            switch (domain.relation) {
+                case "1:N":
+                    if (classId !== domain.targetClass.id) {
+                        throw new Error(`Given classId '${classId}' Reference attributes for domain '${domainName}' can only be added to class '${domain.targetClass}'.`);
+                    }
+                    break;
+                case "N:1":
+                    if (classId !== domain.sourceClass.id) {
+                        throw new Error(`Given classId '${classId}' Reference attributes for domain '${domainName}' can only be added to class '${domain.sourceClass}'.`);
+                    }
+                    break;
+                case "1:1":
+                    if (classId !== domain.sourceClass.id && classId !== domain.targetClass.id) {
+                        throw new Error(`Class '${classId}' is not part of domain '${domainName}'.`);
+                    }
+                    break;
+                case "N:N":
+                    throw new Error(`Domain '${domainName}' does not support reference attributes.`);
+                default:
+                    throw new Error(`Unsupported relation '${domain.relation}' for domain '${domainName}'.`);
+            }
+        };
+        this.setField = () => {
+            const { name, type, config } = this.model;
+            let field;
+            switch (type) {
+                // ... existing cases for 'string', 'number', 'boolean', 'date' ...
+                case 'string':
+                    field = z.string();
+                    if (config.maxLength !== undefined) {
+                        field = field.max(config.maxLength);
+                    }
+                    break;
+                case 'integer':
+                    field = z.number();
+                    if (typeof config.min === 'number') {
+                        field = field.min(config.min);
+                    }
+                    if (typeof config.max === 'number') {
+                        field = field.max(config.max);
+                    }
+                    break;
+                // case 'date':
+                //     field = z.date();
+                //     break;
+                case 'decimal':
+                    field = z.number();
+                    // min and max validation
+                    if (typeof config.min === 'number') {
+                        field = field.min(config.min);
+                    }
+                    if (typeof config.max === 'number') {
+                        field = field.max(config.max);
+                    }
+                    // decimal precision validation (with refinement)
+                    if (typeof config.precision === 'number' && config.precision >= 0) {
+                        const isPrecise = (value) => {
+                            if (typeof value !== 'number')
+                                return true;
+                            const valueAsString = value.toString();
+                            const decimalPart = valueAsString.split('.')[1];
+                            const decimalPlaces = decimalPart ? decimalPart.length : 0;
+                            return decimalPlaces <= config.precision;
+                        };
+                        field = field.refine(isPrecise, `Number cannot have more than ${config.precision} decimals.`);
+                    }
+                    break;
+                case 'boolean':
+                    field = z.boolean();
+                    break;
+                case "object":
+                    field = z.object({});
+                    break;
+                case 'enum':
+                    if (!config.values || !Array.isArray(config.values) || config.values.length === 0) {
+                        throw new Error(`Attribute '${name}' of type 'enum' must have a non-empty 'values' array in its config.`);
+                    }
+                    const enumValues = config.values.map(v => v.value);
+                    field = z.enum(enumValues);
+                    break;
+                case 'foreign_key':
+                    if (!config.targetClass) {
+                        throw new Error(`Attribute '${name}' of type 'foreign_key' is missing a 'targetClass' in its config.`);
+                    }
+                    const foreignClass = config.targetClass;
+                    const baseSchema = z.string();
+                    field = baseSchema.refine(async (documentIdOrIds) => {
+                        var _b;
+                        const idsToValidate = Array.isArray(documentIdOrIds) ? documentIdOrIds : [documentIdOrIds];
+                        if (idsToValidate.length === 0) {
+                            return true;
+                        }
+                        try {
+                            if (this.class) {
+                                const stack = this.class.getStack();
+                                if (stack) {
+                                    const promises = idsToValidate.map(id => stack.db.get(id));
+                                    const fetchResult = await Promise.all(promises);
+                                    return true;
+                                }
+                                else
+                                    throw new Error("Missing stack connection");
+                            }
+                            else
+                                throw new Error("Missing class parentship");
+                        }
+                        catch (error) {
+                            if (error.status === 404) {
+                                console.error(`Foreign key validation failed: document not found in class '${foreignClass}'. ${(_b = this.class) === null || _b === void 0 ? void 0 : _b.getName()}`, { error });
+                                return false;
+                            }
+                            throw error;
+                        }
+                    }, {
+                        message: `One or more documents not found in class '${foreignClass}'.`,
+                    });
+                    break;
+                case 'reference':
+                    field = z.string().min(1);
+                    break;
+                default:
+                    throw new Error(`Unsupported schema type: '${type}' for field '${name}'`);
+            }
+            // These rules are applied regardless of the type, and in the correct order
+            if (config.defaultValue) {
+                field = field.default(config.defaultValue);
+            }
+            if (config.mandatory !== true) {
+                field = field.optional();
+            }
+            if (config.isArray === true) {
+                field = z.array(field);
+            }
+            this.field = field;
+        };
+        this.isPrimaryKey = () => {
+            let model = this.getModel();
+            return !!model.config.primaryKey;
+        };
+        this.isMandatory = () => {
+            return !!this.model.config.mandatory;
+        };
+        this.getModel = () => {
+            return this.model;
+        };
+        this.getClass = () => {
+            if (this.class)
+                return this.class;
+            else
+                throw Error("Missing class configuration for this attribute");
+        };
+        this.validate = async (data) => {
+            return this.field.safeParseAsync(data);
+        };
+        this.setModel = (model) => {
+            let currentModel = this.getModel();
+            model = Object.assign(currentModel || {}, model);
+            this.model = model;
+            this.defaultValue = model.config.defaultValue;
+        };
+        // TODO: Better define config
+        this.getType = (type) => {
+            if (this.checkTypeValidity(type)) {
+                return type;
+            }
+            else
+                throw Error("Invalid attribute type: " + type);
+            // return this?
+        };
+        this.getEmpty = () => {
+            // Let the field handle the default value, if present
+            // if not, it's undefined
+            const partialDoc = {
+                [this.name]: this.field.parse(undefined) || null
+            };
+            return partialDoc;
+        };
+        // getType()
+        this.getName = () => {
+            return this.name;
+        };
+        this.checkTypeValidity = (type) => {
+            let validity = false;
+            if (ATTRIBUTE_TYPES.includes(type)) {
+                validity = true;
+            }
+            return validity;
+        };
+        // TODO: change to imported const default configs for types
+        // as of now it accepts only string
+        // TODO: since config depends on attribute's type, 
+        // find a way to check if given configs are correct
+        // find a way to add default configs base on type
+        this.getTypeConf = (type, config) => {
+            switch (type) {
+                // TODO: add missing cases and change values to imported const 
+                case "decimal":
+                    config = Object.assign({ max: null, min: null, precision: null, isArray: false }, config);
+                    break;
+                case "integer":
+                    config = Object.assign({ max: null, min: null, isArray: false }, config);
+                    break;
+                case "string":
+                    config = Object.assign({ isArray: false }, config);
+                    break;
+                case "object":
+                    config = Object.assign({ isArray: false }, config);
+                    break;
+                case "date":
+                    config = Object.assign({ format: "iso", max: null, min: null, isArray: false }, config);
+                    break;
+                case "boolean":
+                    config = Object.assign({ defaultValue: false, isArray: false }, config);
+                    break;
+                case "foreign_key":
+                    config = Object.assign({ targetClass: null, isArray: false }, config);
+                    break;
+                case "enum":
+                    config = Object.assign({ values: [], isArray: false }, config);
+                    break;
+                case "reference":
+                    config = Object.assign({ isArray: false }, config);
+                    break;
+                default:
+                    throw new Error("Unexpected type: " + type);
+                // return "^[a-zA-Z0-9_\\s]".concat("{0,"+config.maxLength+"}$");
+            }
+            return config;
+        };
+        this.name = name;
+        this.description = description;
+        this.setModel({
+            name: this.name,
+            description: this.description,
+            type: this.getType(type),
+            config: this.getTypeConf(type, config) || {},
+        });
+        this.setField();
+        // if it's given a class
+        // if ( classObj ) {
+        // attempt to add attribute
+        this.class = classObj;
+        // }
+    }
+    static async create(classObj, name, type, description, config) {
+        const attribute = new _a(classObj, name, type, description, config);
+        await attribute.ensureReferenceConfigIsValid();
+        await _a.build(attribute);
+        return attribute;
+    }
+}
+_a = Attribute;
+Attribute.build = async (attributeObj) => {
+    let classObj = attributeObj.getClass();
+    let stack = classObj.getStack();
+    if (stack) {
+        await classObj.addAttribute(attributeObj);
+        return attributeObj;
+    }
+    else {
+        throw new Error("Missing db configuration");
+    }
+};
+export default Attribute;
+//# sourceMappingURL=attribute.js.map