@feltdb/core 0.2.0 → 0.4.0

package/dist/sharding.js

@@ -0,0 +1,317 @@
+/**
+ * Sharding - Horizontal data partitioning for scaling
+ *
+ * Distributes data across shards for linear scalability:
+ * - Consistent hashing for automatic shard assignment
+ * - Hotspot detection based on metrics
+ * - Automatic rebalancing recommendations
+ * - Multi-shard query support
+ */
+/**
+ * Shard Manager - TypeScript implementation
+ */
+export class ShardManager {
+    constructor(shardingKey, strategy = 'consistent-hash') {
+        this.shardRanges = [];
+        this.shardMetrics = new Map();
+        this.rebalanceHistory = [];
+        this.rebalanceThreshold = 0.5;
+        this.shardingKey = shardingKey;
+        this.strategy = strategy;
+    }
+    /**
+     * Hash a value using simple algorithm
+     */
+    hashValue(value) {
+        let hash = 5381;
+        for (let i = 0; i < value.length; i++) {
+            hash = ((hash << 5) + hash) ^ value.charCodeAt(i);
+        }
+        // Convert to positive number in 0 to 2^53 range
+        return Math.abs(hash) % (2 ** 53 - 1);
+    }
+    /**
+     * Initialize shards
+     */
+    initializeShards(shardIds, replicaNodes) {
+        if (shardIds.length === 0)
+            return;
+        const hashSpace = 2 ** 53 - 1;
+        const shardSize = Math.floor(hashSpace / shardIds.length);
+        for (let i = 0; i < shardIds.length; i++) {
+            const shardId = shardIds[i];
+            const startHash = i * shardSize;
+            const endHash = i === shardIds.length - 1 ? hashSpace : (i + 1) * shardSize - 1;
+            this.shardRanges.push({
+                shardId,
+                startHash,
+                endHash,
+                replicaNodes: replicaNodes?.[shardId] ?? [],
+            });
+            this.shardMetrics.set(shardId, {
+                shardId,
+                entryCount: 0,
+                sizeBytes: 0,
+                reads: 0,
+                writes: 0,
+                avgQueryTimeMs: 0,
+            });
+        }
+        // Sort ranges for binary search
+        this.shardRanges.sort((a, b) => a.startHash - b.startHash);
+    }
+    /**
+     * Get shard for a key
+     */
+    getShardForKey(key) {
+        const hash = this.hashValue(key);
+        return this.shardRanges.find((r) => hash >= r.startHash && hash <= r.endHash) ?? null;
+    }
+    /**
+     * Get replica nodes for a key
+     */
+    getReplicasForKey(key) {
+        const shard = this.getShardForKey(key);
+        return shard?.replicaNodes ?? [];
+    }
+    /**
+     * Record a shard operation
+     */
+    recordShardOperation(shardId, operation, timeMs, recordsAffected, sizeBytes) {
+        const metrics = this.shardMetrics.get(shardId);
+        if (!metrics)
+            return;
+        switch (operation) {
+            case 'read':
+                metrics.reads++;
+                const oldAvg = metrics.avgQueryTimeMs;
+                metrics.avgQueryTimeMs = (oldAvg * (metrics.reads - 1) + timeMs) / metrics.reads;
+                break;
+            case 'write':
+                metrics.writes++;
+                metrics.entryCount += recordsAffected;
+                metrics.sizeBytes += sizeBytes;
+                break;
+            case 'delete':
+                metrics.entryCount = Math.max(0, metrics.entryCount - recordsAffected);
+                metrics.sizeBytes = Math.max(0, metrics.sizeBytes - sizeBytes);
+                break;
+        }
+    }
+    /**
+     * Get all shard metrics
+     */
+    getAllMetrics() {
+        return Array.from(this.shardMetrics.values());
+    }
+    /**
+     * Detect hotspots
+     */
+    detectHotspots() {
+        const alerts = [];
+        const allMetrics = this.getAllMetrics();
+        if (allMetrics.length === 0)
+            return alerts;
+        const totalReads = allMetrics.reduce((sum, m) => sum + m.reads, 0);
+        const totalWrites = allMetrics.reduce((sum, m) => sum + m.writes, 0);
+        const totalEntries = allMetrics.reduce((sum, m) => sum + m.entryCount, 0);
+        const numShards = allMetrics.length;
+        const avgReads = totalReads / numShards;
+        const avgWrites = totalWrites / numShards;
+        const avgEntries = totalEntries / numShards;
+        // Calculate standard deviations
+        const readStdDev = this.calculateStdDev(allMetrics.map((m) => m.reads), avgReads);
+        const writeStdDev = this.calculateStdDev(allMetrics.map((m) => m.writes), avgWrites);
+        const entryStdDev = this.calculateStdDev(allMetrics.map((m) => m.entryCount), avgEntries);
+        // Detect hotspots
+        for (const metrics of allMetrics) {
+            // High read load
+            if (readStdDev > 0 && Math.abs(metrics.reads - avgReads) > readStdDev * 2) {
+                alerts.push({
+                    shardId: metrics.shardId,
+                    reason: 'High read load',
+                    metricValue: metrics.reads,
+                    threshold: avgReads + readStdDev * 2,
+                    severity: metrics.reads > avgReads * 2 ? 'high' : 'medium',
+                });
+            }
+            // High write load
+            if (writeStdDev > 0 && Math.abs(metrics.writes - avgWrites) > writeStdDev * 2) {
+                alerts.push({
+                    shardId: metrics.shardId,
+                    reason: 'High write load',
+                    metricValue: metrics.writes,
+                    threshold: avgWrites + writeStdDev * 2,
+                    severity: metrics.writes > avgWrites * 2 ? 'high' : 'medium',
+                });
+            }
+            // Data imbalance
+            if (entryStdDev > 0 && Math.abs(metrics.entryCount - avgEntries) > entryStdDev * 3) {
+                alerts.push({
+                    shardId: metrics.shardId,
+                    reason: 'Data imbalance',
+                    metricValue: metrics.entryCount,
+                    threshold: avgEntries + entryStdDev * 3,
+                    severity: metrics.entryCount > avgEntries * 3 ? 'high' : 'low',
+                });
+            }
+        }
+        return alerts;
+    }
+    /**
+     * Generate rebalance operations
+     */
+    generateRebalanceOps() {
+        const hotspots = this.detectHotspots();
+        const operations = [];
+        for (const hotspot of hotspots) {
+            if (hotspot.severity === 'high') {
+                const shardRange = this.shardRanges.find((r) => r.shardId === hotspot.shardId);
+                if (shardRange) {
+                    const midHash = Math.floor((shardRange.startHash + shardRange.endHash) / 2);
+                    const newShardId = `${hotspot.shardId}-split-${Date.now()}`;
+                    operations.push({
+                        sourceShard: hotspot.shardId,
+                        targetShard: newShardId,
+                        keyRangeStart: midHash,
+                        keyRangeEnd: shardRange.endHash,
+                        estimatedRecords: Math.floor(hotspot.metricValue / 2),
+                        priority: 200,
+                    });
+                }
+            }
+        }
+        return operations;
+    }
+    /**
+     * Get distribution summary
+     */
+    getDistributionSummary() {
+        const allMetrics = this.getAllMetrics();
+        const totalEntries = allMetrics.reduce((sum, m) => sum + m.entryCount, 0);
+        const totalSize = allMetrics.reduce((sum, m) => sum + m.sizeBytes, 0);
+        const totalReads = allMetrics.reduce((sum, m) => sum + m.reads, 0);
+        const totalWrites = allMetrics.reduce((sum, m) => sum + m.writes, 0);
+        const maxEntries = Math.max(...allMetrics.map((m) => m.entryCount), 0);
+        const minEntries = Math.min(...allMetrics.map((m) => m.entryCount), 0);
+        return {
+            numShards: allMetrics.length,
+            totalEntries,
+            totalSizeBytes: totalSize,
+            totalReads,
+            totalWrites,
+            maxEntriesPerShard: maxEntries,
+            minEntriesPerShard: minEntries,
+            imbalanceRatio: minEntries > 0 ? maxEntries / minEntries : 1,
+        };
+    }
+    /**
+     * Record a rebalance operation
+     */
+    recordRebalance(operation) {
+        this.rebalanceHistory.push(operation);
+    }
+    /**
+     * Get rebalance history
+     */
+    getRebalanceHistory() {
+        return this.rebalanceHistory;
+    }
+    /**
+     * Calculate standard deviation
+     */
+    calculateStdDev(values, mean) {
+        if (values.length === 0)
+            return 0;
+        const variance = values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length;
+        return Math.sqrt(variance);
+    }
+}
+/**
+ * Shard Router - Routes queries to appropriate shards
+ */
+export class ShardRouter {
+    constructor(shardManager) {
+        this.shardConnections = new Map(); // Map of shardId to connection
+        this.shardManager = shardManager;
+    }
+    /**
+     * Route a query to appropriate shards
+     */
+    routeQuery(key) {
+        const shard = this.shardManager.getShardForKey(key);
+        if (!shard)
+            return [];
+        // Return primary shard + replicas
+        return [shard.shardId, ...shard.replicaNodes];
+    }
+    /**
+     * Route a range query to multiple shards
+     */
+    routeRangeQuery(keyPattern) {
+        // For range queries, we might need multiple shards
+        // This is a simplified implementation
+        const shards = new Set();
+        const allMetrics = this.shardManager.getAllMetrics();
+        for (const metrics of allMetrics) {
+            shards.add(metrics.shardId);
+        }
+        return Array.from(shards);
+    }
+    /**
+     * Register shard connection
+     */
+    registerShardConnection(shardId, connection) {
+        this.shardConnections.set(shardId, connection);
+    }
+    /**
+     * Get shard connection
+     */
+    getShardConnection(shardId) {
+        return this.shardConnections.get(shardId);
+    }
+}
+/**
+ * Rebalancer - Coordinates data migration between shards
+ */
+export class Rebalancer {
+    constructor(shardManager, shardRouter) {
+        this.rebalanceInProgress = false;
+        this.shardManager = shardManager;
+        this.shardRouter = shardRouter;
+    }
+    /**
+     * Start automatic rebalancing
+     */
+    async startAutoRebalance(intervalMs = 60000) {
+        setInterval(async () => {
+            if (!this.rebalanceInProgress) {
+                await this.performRebalance();
+            }
+        }, intervalMs);
+    }
+    /**
+     * Perform rebalancing
+     */
+    async performRebalance() {
+        this.rebalanceInProgress = true;
+        try {
+            const operations = this.shardManager.generateRebalanceOps();
+            for (const operation of operations) {
+                console.debug(`Rebalancing: ${operation.sourceShard} → ${operation.targetShard}`);
+                // In real implementation, this would coordinate data migration
+                this.shardManager.recordRebalance(operation);
+            }
+        }
+        finally {
+            this.rebalanceInProgress = false;
+        }
+    }
+    /**
+     * Check if rebalancing is needed
+     */
+    isRebalanceNeeded() {
+        const hotspots = this.shardManager.detectHotspots();
+        return hotspots.some((h) => h.severity === 'high');
+    }
+}

package/dist/state-contract.d.ts

@@ -0,0 +1,173 @@
+/** Transport types for the Rust-owned FeltDB state contract. */
+export type PrimitiveType = 'string' | 'integer' | 'number' | 'boolean' | 'timestamp' | 'json';
+export type FieldType = {
+    kind: 'primitive';
+    primitive: PrimitiveType;
+} | {
+    kind: 'enum';
+    values: string[];
+} | {
+    kind: 'reference';
+    collection: string;
+} | {
+    kind: 'array';
+    items: FieldType;
+};
+export interface StateField {
+    name: string;
+    field_type: FieldType;
+    nullable?: boolean;
+    required?: boolean;
+    default?: unknown;
+    constraints?: {
+        minimum?: number;
+        maximum?: number;
+        min_length?: number;
+        max_length?: number;
+        pattern?: string;
+    };
+    computed?: string;
+}
+export interface StateSchema {
+    contract_version: number;
+    schema_version: number;
+    application_id: string;
+    revision_id: string;
+    collections: {
+        name: string;
+        version: number;
+        fields: StateField[];
+        indexes: {
+            name: string;
+            fields: string[];
+            unique?: boolean;
+            sparse?: boolean;
+            version: number;
+        }[];
+    }[];
+}
+export type QueryFilter = {
+    operator: 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte';
+    field: string;
+    value: unknown;
+} | {
+    operator: 'in';
+    field: string;
+    values: unknown[];
+} | {
+    operator: 'contains';
+    field: string;
+    value: unknown;
+} | {
+    operator: 'startsWith' | 'endsWith';
+    field: string;
+    value: string;
+} | {
+    operator: 'exists';
+    field: string;
+    exists: boolean;
+} | {
+    operator: 'and' | 'or';
+    filters: QueryFilter[];
+} | {
+    operator: 'not';
+    filter: QueryFilter;
+};
+export interface CanonicalQuery {
+    collection: string;
+    filter?: QueryFilter;
+    order_by?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    }[];
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+    projection?: string[];
+    group_by?: string[];
+    aggregates?: {
+        name: string;
+        function: 'count' | 'sum' | 'avg' | 'min' | 'max';
+        field?: string;
+    }[];
+    references?: {
+        field: string;
+        collection: string;
+        projection?: string[];
+        as_name: string;
+    }[];
+}
+export interface QueryResult<T = Record<string, unknown>> {
+    query_id: string;
+    query_hash: string;
+    application_revision: string;
+    schema_version: number;
+    state_version: number;
+    causal_cursor: Record<string, number>;
+    records: T[];
+    aggregates: Record<string, unknown>[];
+    next_cursor?: string;
+    plan: {
+        implementation: string;
+        collection: string;
+        index?: string;
+        scan_fallback: boolean;
+    };
+}
+export interface TransactionOperation {
+    kind: 'insert' | 'update' | 'delete';
+    collection: string;
+    id: string;
+    value?: unknown;
+    if_version?: number;
+}
+export interface TransactionResult {
+    transaction_id: string;
+    state_before: number;
+    state_after: number;
+    causal_cursor: Record<string, number>;
+    duplicate: boolean;
+    audit: unknown;
+}
+export interface StateFailure {
+    code: 'VALIDATION_FAILED' | 'PRECONDITION_FAILED' | 'AUTHORIZATION_DENIED' | 'SCHEMA_MISMATCH' | 'CONFLICT' | 'STORAGE_FAILURE' | 'INVALID_QUERY' | 'UNKNOWN_FIELD' | 'UNKNOWN_COLLECTION' | 'UNAUTHORIZED_PROJECTION' | 'INVALID_CURSOR' | 'STATE_UNAVAILABLE';
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+    resource?: string;
+    transaction?: string;
+    causal_position?: number;
+}
+declare class TransactionBuilder {
+    readonly operations: TransactionOperation[];
+    collection(name: string): {
+        insert: (id: string, value: unknown) => string;
+        update: (id: string, value: unknown, options?: {
+            ifVersion?: number;
+        }) => void;
+        delete: (id: string, options?: {
+            ifVersion?: number;
+        }) => void;
+    };
+}
+export declare class StateContractClient {
+    private readonly target;
+    private readonly baseUrl;
+    constructor(target: {
+        applicationId: string;
+        revisionId: string;
+        environment?: string;
+    }, baseUrl?: string);
+    private request;
+    schema(): Promise<{
+        schema: StateSchema;
+    }>;
+    stateVersion(): Promise<unknown>;
+    query<T = Record<string, unknown>>(query: CanonicalQuery): Promise<QueryResult<T>>;
+    transaction(work: (tx: TransactionBuilder) => void | Promise<void>, options?: {
+        transactionId?: string;
+        causalParent?: number;
+    }): Promise<TransactionResult>;
+}
+export {};
+//# sourceMappingURL=state-contract.d.ts.map

package/dist/state-contract.d.ts.map

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

package/dist/state-contract.js

@@ -0,0 +1,24 @@
+class TransactionBuilder {
+    constructor() {
+        this.operations = [];
+    }
+    collection(name) { return { insert: (id, value) => { this.operations.push({ kind: 'insert', collection: name, id, value }); return id; }, update: (id, value, options) => { this.operations.push({ kind: 'update', collection: name, id, value, if_version: options?.ifVersion }); }, delete: (id, options) => { this.operations.push({ kind: 'delete', collection: name, id, if_version: options?.ifVersion }); } }; }
+}
+export class StateContractClient {
+    constructor(target, baseUrl = '') {
+        this.target = target;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, options) { const response = await fetch(`${this.baseUrl}${path}`, { ...options, headers: { ...(options?.body ? { 'Content-Type': 'application/json' } : {}), ...options?.headers } }); const body = await response.json(); if (!response.ok) {
+        let failure = body;
+        try {
+            failure = JSON.parse(body.error);
+        }
+        catch { }
+        throw Object.assign(new Error(failure?.message || body.error || 'FeltDB state request failed'), { status: response.status, failure });
+    } return body; }
+    schema() { const q = new URLSearchParams({ application_id: this.target.applicationId, revision_id: this.target.revisionId, environment: this.target.environment || 'production' }); return this.request(`/v1/schema?${q}`); }
+    stateVersion() { const q = new URLSearchParams({ application_id: this.target.applicationId, revision_id: this.target.revisionId, environment: this.target.environment || 'production' }); return this.request(`/v1/state/version?${q}`); }
+    query(query) { return this.request('/v1/query', { method: 'POST', body: JSON.stringify({ application_id: this.target.applicationId, revision_id: this.target.revisionId, environment: this.target.environment || 'production', query }) }); }
+    async transaction(work, options) { const tx = new TransactionBuilder(); await work(tx); return this.request('/v1/transactions', { method: 'POST', body: JSON.stringify({ application_id: this.target.applicationId, revision_id: this.target.revisionId, environment: this.target.environment || 'production', transaction: { transaction_id: options?.transactionId, tenant_id: 'transport', application_id: this.target.applicationId, revision_id: this.target.revisionId, schema_version: 0, causal_parent: options?.causalParent, authorization: { subject: 'transport', tenant_id: 'transport', application_id: this.target.applicationId, revision_id: this.target.revisionId, capabilities: [] }, operations: tx.operations } }) }); }
+}

package/dist/sync-contract.d.ts

@@ -0,0 +1,101 @@
+import type { SignedGrant, AuthorizationContext, AuthorizationResource, AuthorizationSubject } from './authorization.js';
+export type SyncStatus = 'offline' | 'connecting' | 'syncing' | 'synced' | 'degraded';
+export interface SyncScope {
+    resources?: string[];
+    collections?: string[];
+    fields?: Record<string, string[]>;
+}
+export interface SyncCursor {
+    contract_version: 1;
+    tenant_id: string;
+    application_id: string;
+    subject: AuthorizationSubject;
+    scope_hash: string;
+    position: number;
+}
+export interface SyncOperation {
+    contract_version: 1;
+    operation_id: string;
+    tenant_id: string;
+    application_id: string;
+    subject: AuthorizationSubject;
+    device_id: string;
+    resource: AuthorizationResource;
+    operation: {
+        kind: 'insert' | 'update' | 'delete';
+        collection: string;
+        id: string;
+        value?: unknown;
+        if_version?: number;
+    };
+    causal_context: Record<string, number>;
+    schema_version: number;
+    authorization_context: AuthorizationContext;
+    offline_grant: SignedGrant;
+    application_revision: string;
+    created_at: number;
+}
+export interface SyncResult {
+    acknowledgements: Array<{
+        operation_id: string;
+        outcome: string;
+        server_position?: number;
+    }>;
+    rejections: Array<{
+        operation_id: string;
+        code: string;
+        message: string;
+        retryable: boolean;
+    }>;
+    conflicts: Array<{
+        operation_id: string;
+        reason: string;
+    }>;
+    cursor: SyncCursor;
+}
+export interface SyncConfig {
+    endpoint?: string;
+    scope: SyncScope;
+    device: {
+        device_id: string;
+        tenant_id: string;
+        application_id: string;
+        subject: AuthorizationSubject;
+    };
+    offlineGrant: SignedGrant;
+    fetcher?: typeof fetch;
+}
+declare class StatusSignal {
+    private value;
+    private listeners;
+    constructor(value?: SyncStatus);
+    subscribe(listener: (status: SyncStatus) => void): () => boolean;
+    set(value: SyncStatus): void;
+    get(): SyncStatus;
+}
+export declare class SyncController {
+    private config;
+    readonly status: StatusSignal;
+    private readonly fetcher;
+    private sessionId?;
+    private cursor?;
+    private error?;
+    private timer?;
+    constructor(config: SyncConfig);
+    private key;
+    private restore;
+    private persist;
+    private readOutbox;
+    private writeOutbox;
+    private request;
+    start(): Promise<this>;
+    stop(): Promise<void>;
+    enqueue(operation: SyncOperation): string;
+    flush(): Promise<void>;
+    pending(): SyncOperation[];
+    conflicts(): SyncOperation[];
+    lastCursor(): SyncCursor | undefined;
+    lastError(): string | undefined;
+}
+export {};
+//# sourceMappingURL=sync-contract.d.ts.map

package/dist/sync-contract.d.ts.map

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