@maadb/core 0.0.1 → 0.7.9

package/dist/engine/mutex.js

@@ -0,0 +1,50 @@
+// ============================================================================
+// AsyncFifoMutex — FIFO-ordered async mutual exclusion
+// Callers acquire, do work, call release(). Order is strictly first-in-first-out.
+// Zero external dependencies. No timeout (deferred to 0.8.5).
+// ============================================================================
+export class AsyncFifoMutex {
+    queue = [];
+    held = false;
+    /**
+     * Acquire the lock. Returns a release function. Callers MUST call release()
+     * in a finally block to avoid leaks.
+     *
+     * Ordering is FIFO: the first caller to await acquire() is the first to be
+     * granted the lock when it becomes available.
+     */
+    acquire() {
+        return new Promise((resolve) => {
+            const grant = (release) => {
+                this.held = true;
+                resolve(release);
+            };
+            if (!this.held) {
+                grant(() => this.release());
+            }
+            else {
+                this.queue.push(grant);
+            }
+        });
+    }
+    release() {
+        this.held = false;
+        const next = this.queue.shift();
+        if (next)
+            next(() => this.release());
+    }
+    /**
+     * Current pressure on the lock: 1 if held and no waiters, >1 if waiters are
+     * queued, 0 if idle. Used for health reporting and drain loops.
+     */
+    depth() {
+        return this.queue.length + (this.held ? 1 : 0);
+    }
+    /**
+     * True if the lock is currently held by a caller.
+     */
+    isHeld() {
+        return this.held;
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/engine/mutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/engine/mutex.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uDAAuD;AACvD,kFAAkF;AAClF,8DAA8D;AAC9D,+EAA+E;AAI/E,MAAM,OAAO,cAAc;IACjB,KAAK,GAAsC,EAAE,CAAC;IAC9C,IAAI,GAAG,KAAK,CAAC;IAErB;;;;;;OAMG;IACH,OAAO;QACL,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;YACtC,MAAM,KAAK,GAAG,CAAC,OAAgB,EAAE,EAAE;gBACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;gBACjB,OAAO,CAAC,OAAO,CAAC,CAAC;YACnB,CAAC,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,OAAO;QACb,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,IAAI;YAAE,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/engine/pathguard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check that a target path is contained within the root directory.
+ * Uses path.resolve for canonicalization, not startsWith on raw strings.
+ * Handles ../, sibling paths, and trailing separators.
+ */
+export declare function isContainedIn(targetPath: string, rootDir: string): boolean;
+/**
+ * Same check but follows symlinks to their real paths.
+ * Use when the target path already exists on disk.
+ */
+export declare function isReallyContainedIn(targetPath: string, rootDir: string): boolean;
+/**
+ * Assert containment or throw. Use at validation boundaries.
+ */
+export declare function assertContainedIn(targetPath: string, rootDir: string, context: string): void;
+//# sourceMappingURL=pathguard.d.ts.map

package/dist/engine/pathguard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathguard.d.ts","sourceRoot":"","sources":["../../src/engine/pathguard.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAShF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI5F"}

package/dist/engine/pathguard.js

@@ -0,0 +1,41 @@
+// ============================================================================
+// Path Guard — canonicalized containment checks
+// Prevents path traversal attacks (../, sibling dirs, symlinks)
+// ============================================================================
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+/**
+ * Check that a target path is contained within the root directory.
+ * Uses path.resolve for canonicalization, not startsWith on raw strings.
+ * Handles ../, sibling paths, and trailing separators.
+ */
+export function isContainedIn(targetPath, rootDir) {
+    const resolvedRoot = path.resolve(rootDir) + path.sep;
+    const resolvedTarget = path.resolve(targetPath);
+    // Target must either equal root or start with root + separator
+    return resolvedTarget === path.resolve(rootDir) || resolvedTarget.startsWith(resolvedRoot);
+}
+/**
+ * Same check but follows symlinks to their real paths.
+ * Use when the target path already exists on disk.
+ */
+export function isReallyContainedIn(targetPath, rootDir) {
+    try {
+        const realRoot = realpathSync(rootDir) + path.sep;
+        const realTarget = realpathSync(targetPath);
+        return realTarget === realpathSync(rootDir) || realTarget.startsWith(realRoot);
+    }
+    catch {
+        // If realpath fails (file doesn't exist), fall back to resolve check
+        return isContainedIn(targetPath, rootDir);
+    }
+}
+/**
+ * Assert containment or throw. Use at validation boundaries.
+ */
+export function assertContainedIn(targetPath, rootDir, context) {
+    if (!isContainedIn(targetPath, rootDir)) {
+        throw new Error(`Path escape rejected (${context}): ${targetPath} is outside ${rootDir}`);
+    }
+}
+//# sourceMappingURL=pathguard.js.map

package/dist/engine/pathguard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathguard.js","sourceRoot":"","sources":["../../src/engine/pathguard.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gDAAgD;AAChD,gEAAgE;AAChE,+EAA+E;AAE/E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,OAAe;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;IACtD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAChD,+DAA+D;IAC/D,OAAO,cAAc,KAAK,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,OAAe;IACrE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;QAClD,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;QAC5C,OAAO,UAAU,KAAK,YAAY,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,OAAO,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,OAAe,EAAE,OAAe;IACpF,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,MAAM,UAAU,eAAe,OAAO,EAAE,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC"}

package/dist/engine/reads.d.ts

@@ -0,0 +1,24 @@
+import { type Result } from '../errors.js';
+import { type DocId, type DocType, type SchemaDefinition, type DocumentQuery, type ObjectQuery, type FilterCondition } from '../types.js';
+import type { EngineContext } from './context.js';
+import type { GetResult, FindResult, SearchResult, RelatedResult, DescribeResult, SummaryResult, SchemaInfoResult, VerifyResult, AggregateQuery, AggregateResult, JoinQuery, JoinResult, ChangesSinceQuery, ChangesPage, ChangesSinceParsedCursor } from './types.js';
+export declare function getDocument(ctx: EngineContext, id: DocId, depth: 'hot' | 'warm' | 'cold', blockIdOrHeading?: string | undefined): Promise<Result<GetResult>>;
+export declare const MAX_QUERY_LIMIT = 500;
+export declare const MAX_AGGREGATE_LIMIT = 2000;
+export declare function expandFilters(raw: Record<string, unknown> | undefined): Result<Record<string, FilterCondition[]>>;
+export declare function findDocuments(ctx: EngineContext, query: DocumentQuery): Result<FindResult>;
+export declare function searchObjects(ctx: EngineContext, query: ObjectQuery): Result<SearchResult>;
+export declare function listRelated(ctx: EngineContext, id: DocId, direction: 'outgoing' | 'incoming' | 'both', types?: DocType[] | undefined): Result<RelatedResult>;
+export declare function describe(ctx: EngineContext): DescribeResult;
+export declare function summary(ctx: EngineContext): SummaryResult;
+export declare function getSchema(ctx: EngineContext, dt: DocType): SchemaDefinition | undefined;
+export declare function schemaInfo(ctx: EngineContext, dt: DocType): Result<SchemaInfoResult>;
+export declare const UNRESOLVED_GROUP_KEY = "__unresolved__";
+export declare function aggregate(ctx: EngineContext, query: AggregateQuery): Result<AggregateResult>;
+export declare function join(ctx: EngineContext, query: JoinQuery): Result<JoinResult>;
+export declare function verifyField(ctx: EngineContext, id: DocId, field: string, expected: unknown): Promise<Result<VerifyResult>>;
+export declare function verifyCount(ctx: EngineContext, dt: DocType, expectedCount: number, filters?: Record<string, import('../types.js').FilterCondition>): Result<VerifyResult>;
+export declare function encodeChangesCursor(cursor: ChangesSinceParsedCursor): string;
+export declare function decodeChangesCursor(raw: string): Result<ChangesSinceParsedCursor>;
+export declare function changesSince(ctx: EngineContext, query: ChangesSinceQuery): Result<ChangesPage>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/engine/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/engine/reads.ts"],"names":[],"mappings":"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"}