duckpond 0.1.0

package/dist/types.d.mts

@@ -0,0 +1,182 @@
+import { DuckDBConnection } from '@duckdb/node-api';
+import { Either } from 'functype/either';
+
+/**
+ * Configuration for DuckPond manager
+ */
+interface DuckPondConfig {
+    r2?: {
+        accountId: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        bucket: string;
+    };
+    s3?: {
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        bucket: string;
+        endpoint?: string;
+    };
+    memoryLimit?: string;
+    threads?: number;
+    tempDir?: string;
+    maxActiveUsers?: number;
+    evictionTimeout?: number;
+    cacheType?: "disk" | "memory" | "noop";
+    cacheDir?: string;
+    strategy?: "parquet" | "duckdb" | "hybrid";
+}
+/**
+ * Represents an active user database connection
+ */
+interface UserDatabase {
+    userId: string;
+    connection: DuckDBConnection;
+    lastAccess: Date;
+    attached: boolean;
+    memoryUsage?: number;
+}
+/**
+ * Statistics about a user's database
+ */
+interface UserStats {
+    userId: string;
+    attached: boolean;
+    lastAccess: Date;
+    memoryUsage: number;
+    storageUsage: number;
+    queryCount: number;
+}
+/**
+ * Database schema information
+ */
+interface Schema {
+    tables: TableSchema[];
+}
+interface TableSchema {
+    name: string;
+    columns: ColumnSchema[];
+    rowCount?: number;
+}
+interface ColumnSchema {
+    name: string;
+    type: string;
+    nullable: boolean;
+}
+/**
+ * Options for creating a new user
+ */
+interface CreateUserOptions {
+    template?: string;
+    initialData?: Record<string, unknown[]>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storage usage statistics
+ */
+interface StorageStats {
+    totalSize: number;
+    fileCount: number;
+    lastModified: Date;
+    files?: FileInfo[];
+}
+interface FileInfo {
+    path: string;
+    size: number;
+    modified: Date;
+}
+/**
+ * Query result with metadata
+ */
+interface QueryResult<T = unknown> {
+    rows: T[];
+    rowCount: number;
+    executionTime: number;
+    columns: string[];
+}
+/**
+ * Metrics for monitoring
+ */
+interface DuckPondMetrics {
+    activeUsers: number;
+    totalQueries: number;
+    avgQueryTime: number;
+    cacheHitRate: number;
+    memoryUsage: number;
+    storageUsage: number;
+}
+/**
+ * Events emitted by DuckPond
+ */
+type DuckPondEvent = {
+    type: "user:attached";
+    userId: string;
+    timestamp: Date;
+} | {
+    type: "user:detached";
+    userId: string;
+    reason: "eviction" | "manual";
+    timestamp: Date;
+} | {
+    type: "query:executed";
+    userId: string;
+    duration: number;
+    timestamp: Date;
+} | {
+    type: "query:failed";
+    userId: string;
+    error: string;
+    timestamp: Date;
+} | {
+    type: "cache:hit";
+    userId: string;
+} | {
+    type: "cache:miss";
+    userId: string;
+} | {
+    type: "error";
+    error: Error;
+    timestamp: Date;
+};
+/**
+ * Type-safe result types using functype Either
+ */
+type DuckPondResult<T> = Either<DuckPondError, T>;
+type AsyncDuckPondResult<T> = Promise<Either<DuckPondError, T>>;
+/**
+ * Error types
+ */
+interface DuckPondError {
+    code: ErrorCode;
+    message: string;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+declare enum ErrorCode {
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    R2_CONNECTION_ERROR = "R2_CONNECTION_ERROR",
+    S3_CONNECTION_ERROR = "S3_CONNECTION_ERROR",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    USER_ALREADY_EXISTS = "USER_ALREADY_EXISTS",
+    USER_NOT_ATTACHED = "USER_NOT_ATTACHED",
+    QUERY_EXECUTION_ERROR = "QUERY_EXECUTION_ERROR",
+    QUERY_TIMEOUT = "QUERY_TIMEOUT",
+    INVALID_SQL = "INVALID_SQL",
+    MEMORY_LIMIT_EXCEEDED = "MEMORY_LIMIT_EXCEEDED",
+    STORAGE_ERROR = "STORAGE_ERROR",
+    STORAGE_QUOTA_EXCEEDED = "STORAGE_QUOTA_EXCEEDED",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    NOT_INITIALIZED = "NOT_INITIALIZED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Configuration with defaults applied
+ */
+type ResolvedConfig = Required<Omit<DuckPondConfig, "r2" | "s3"> & {
+    r2: DuckPondConfig["r2"];
+    s3: DuckPondConfig["s3"];
+}>;
+
+export { type AsyncDuckPondResult, type ColumnSchema, type CreateUserOptions, type DuckPondConfig, type DuckPondError, type DuckPondEvent, type DuckPondMetrics, type DuckPondResult, ErrorCode, type FileInfo, type QueryResult, type ResolvedConfig, type Schema, type StorageStats, type TableSchema, type UserDatabase, type UserStats };

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+import { DuckDBConnection } from '@duckdb/node-api';
+import { Either } from 'functype/either';
+
+/**
+ * Configuration for DuckPond manager
+ */
+interface DuckPondConfig {
+    r2?: {
+        accountId: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        bucket: string;
+    };
+    s3?: {
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        bucket: string;
+        endpoint?: string;
+    };
+    memoryLimit?: string;
+    threads?: number;
+    tempDir?: string;
+    maxActiveUsers?: number;
+    evictionTimeout?: number;
+    cacheType?: "disk" | "memory" | "noop";
+    cacheDir?: string;
+    strategy?: "parquet" | "duckdb" | "hybrid";
+}
+/**
+ * Represents an active user database connection
+ */
+interface UserDatabase {
+    userId: string;
+    connection: DuckDBConnection;
+    lastAccess: Date;
+    attached: boolean;
+    memoryUsage?: number;
+}
+/**
+ * Statistics about a user's database
+ */
+interface UserStats {
+    userId: string;
+    attached: boolean;
+    lastAccess: Date;
+    memoryUsage: number;
+    storageUsage: number;
+    queryCount: number;
+}
+/**
+ * Database schema information
+ */
+interface Schema {
+    tables: TableSchema[];
+}
+interface TableSchema {
+    name: string;
+    columns: ColumnSchema[];
+    rowCount?: number;
+}
+interface ColumnSchema {
+    name: string;
+    type: string;
+    nullable: boolean;
+}
+/**
+ * Options for creating a new user
+ */
+interface CreateUserOptions {
+    template?: string;
+    initialData?: Record<string, unknown[]>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storage usage statistics
+ */
+interface StorageStats {
+    totalSize: number;
+    fileCount: number;
+    lastModified: Date;
+    files?: FileInfo[];
+}
+interface FileInfo {
+    path: string;
+    size: number;
+    modified: Date;
+}
+/**
+ * Query result with metadata
+ */
+interface QueryResult<T = unknown> {
+    rows: T[];
+    rowCount: number;
+    executionTime: number;
+    columns: string[];
+}
+/**
+ * Metrics for monitoring
+ */
+interface DuckPondMetrics {
+    activeUsers: number;
+    totalQueries: number;
+    avgQueryTime: number;
+    cacheHitRate: number;
+    memoryUsage: number;
+    storageUsage: number;
+}
+/**
+ * Events emitted by DuckPond
+ */
+type DuckPondEvent = {
+    type: "user:attached";
+    userId: string;
+    timestamp: Date;
+} | {
+    type: "user:detached";
+    userId: string;
+    reason: "eviction" | "manual";
+    timestamp: Date;
+} | {
+    type: "query:executed";
+    userId: string;
+    duration: number;
+    timestamp: Date;
+} | {
+    type: "query:failed";
+    userId: string;
+    error: string;
+    timestamp: Date;
+} | {
+    type: "cache:hit";
+    userId: string;
+} | {
+    type: "cache:miss";
+    userId: string;
+} | {
+    type: "error";
+    error: Error;
+    timestamp: Date;
+};
+/**
+ * Type-safe result types using functype Either
+ */
+type DuckPondResult<T> = Either<DuckPondError, T>;
+type AsyncDuckPondResult<T> = Promise<Either<DuckPondError, T>>;
+/**
+ * Error types
+ */
+interface DuckPondError {
+    code: ErrorCode;
+    message: string;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+declare enum ErrorCode {
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT",
+    R2_CONNECTION_ERROR = "R2_CONNECTION_ERROR",
+    S3_CONNECTION_ERROR = "S3_CONNECTION_ERROR",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    USER_ALREADY_EXISTS = "USER_ALREADY_EXISTS",
+    USER_NOT_ATTACHED = "USER_NOT_ATTACHED",
+    QUERY_EXECUTION_ERROR = "QUERY_EXECUTION_ERROR",
+    QUERY_TIMEOUT = "QUERY_TIMEOUT",
+    INVALID_SQL = "INVALID_SQL",
+    MEMORY_LIMIT_EXCEEDED = "MEMORY_LIMIT_EXCEEDED",
+    STORAGE_ERROR = "STORAGE_ERROR",
+    STORAGE_QUOTA_EXCEEDED = "STORAGE_QUOTA_EXCEEDED",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    NOT_INITIALIZED = "NOT_INITIALIZED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Configuration with defaults applied
+ */
+type ResolvedConfig = Required<Omit<DuckPondConfig, "r2" | "s3"> & {
+    r2: DuckPondConfig["r2"];
+    s3: DuckPondConfig["s3"];
+}>;
+
+export { type AsyncDuckPondResult, type ColumnSchema, type CreateUserOptions, type DuckPondConfig, type DuckPondError, type DuckPondEvent, type DuckPondMetrics, type DuckPondResult, ErrorCode, type FileInfo, type QueryResult, type ResolvedConfig, type Schema, type StorageStats, type TableSchema, type UserDatabase, type UserStats };

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkE5ZZH3QBjs = require('./chunk-E5ZZH3QB.js');require('./chunk-5XGN7UAV.js');exports.ErrorCode = _chunkE5ZZH3QBjs.a;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/jordanburke/IdeaProjects/duckpond/dist/types.js"],"names":[],"mappings":"AAAA,+HAAkC,+BAA4B,uCAAuB","file":"/home/jordanburke/IdeaProjects/duckpond/dist/types.js"}

package/dist/types.mjs

@@ -0,0 +1,2 @@
+import{a}from"./chunk-DTZ5B6AO.mjs";import"./chunk-V57JCP3U.mjs";export{a as ErrorCode};
+//# sourceMappingURL=types.mjs.map

package/dist/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/utils/errors.d.mts

@@ -0,0 +1,40 @@
+import { Either } from 'functype';
+import { ErrorCode, DuckPondError } from '../types.mjs';
+import '@duckdb/node-api';
+import 'functype/either';
+
+/**
+ * Create a DuckPondError as a Left Either
+ */
+declare function createError(code: ErrorCode, message: string, cause?: Error, context?: Record<string, unknown>): Either<DuckPondError, never>;
+/**
+ * Wrap a value in a Right Either
+ */
+declare function success<T = void>(value?: T): Either<DuckPondError, T extends void ? void : T>;
+/**
+ * Convert an unknown error to a DuckPondError
+ */
+declare function toDuckPondError(error: unknown, defaultCode?: ErrorCode): DuckPondError;
+/**
+ * Error factory functions for common errors
+ */
+declare const Errors: {
+    connectionFailed: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    r2ConnectionError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    s3ConnectionError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    userNotFound: (userId: string) => Either<DuckPondError, never>;
+    userAlreadyExists: (userId: string) => Either<DuckPondError, never>;
+    userNotAttached: (userId: string) => Either<DuckPondError, never>;
+    queryExecutionError: (message: string, sql?: string, cause?: Error) => Either<DuckPondError, never>;
+    queryTimeout: (timeoutMs: number) => Either<DuckPondError, never>;
+    memoryLimitExceeded: (limit: string) => Either<DuckPondError, never>;
+    storageError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    invalidConfig: (message: string) => Either<DuckPondError, never>;
+    notInitialized: () => Either<DuckPondError, never>;
+};
+/**
+ * Format an error for logging
+ */
+declare function formatError(error: DuckPondError): string;
+
+export { Errors, createError, formatError, success, toDuckPondError };

package/dist/utils/errors.d.ts

@@ -0,0 +1,40 @@
+import { Either } from 'functype';
+import { ErrorCode, DuckPondError } from '../types.js';
+import '@duckdb/node-api';
+import 'functype/either';
+
+/**
+ * Create a DuckPondError as a Left Either
+ */
+declare function createError(code: ErrorCode, message: string, cause?: Error, context?: Record<string, unknown>): Either<DuckPondError, never>;
+/**
+ * Wrap a value in a Right Either
+ */
+declare function success<T = void>(value?: T): Either<DuckPondError, T extends void ? void : T>;
+/**
+ * Convert an unknown error to a DuckPondError
+ */
+declare function toDuckPondError(error: unknown, defaultCode?: ErrorCode): DuckPondError;
+/**
+ * Error factory functions for common errors
+ */
+declare const Errors: {
+    connectionFailed: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    r2ConnectionError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    s3ConnectionError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    userNotFound: (userId: string) => Either<DuckPondError, never>;
+    userAlreadyExists: (userId: string) => Either<DuckPondError, never>;
+    userNotAttached: (userId: string) => Either<DuckPondError, never>;
+    queryExecutionError: (message: string, sql?: string, cause?: Error) => Either<DuckPondError, never>;
+    queryTimeout: (timeoutMs: number) => Either<DuckPondError, never>;
+    memoryLimitExceeded: (limit: string) => Either<DuckPondError, never>;
+    storageError: (message: string, cause?: Error) => Either<DuckPondError, never>;
+    invalidConfig: (message: string) => Either<DuckPondError, never>;
+    notInitialized: () => Either<DuckPondError, never>;
+};
+/**
+ * Format an error for logging
+ */
+declare function formatError(error: DuckPondError): string;
+
+export { Errors, createError, formatError, success, toDuckPondError };

package/dist/utils/errors.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkMZTKR3LRjs = require('../chunk-MZTKR3LR.js');require('../chunk-E5ZZH3QB.js');require('../chunk-5XGN7UAV.js');exports.Errors = _chunkMZTKR3LRjs.d; exports.createError = _chunkMZTKR3LRjs.a; exports.formatError = _chunkMZTKR3LRjs.e; exports.success = _chunkMZTKR3LRjs.b; exports.toDuckPondError = _chunkMZTKR3LRjs.c;
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/jordanburke/IdeaProjects/duckpond/dist/utils/errors.js"],"names":[],"mappings":"AAAA,gIAA2C,gCAA6B,gCAA6B,4MAAwF","file":"/home/jordanburke/IdeaProjects/duckpond/dist/utils/errors.js"}

package/dist/utils/errors.mjs

@@ -0,0 +1,2 @@
+import{a,b,c,d,e}from"../chunk-PCQEPXO3.mjs";import"../chunk-DTZ5B6AO.mjs";import"../chunk-V57JCP3U.mjs";export{d as Errors,a as createError,e as formatError,b as success,c as toDuckPondError};
+//# sourceMappingURL=errors.mjs.map

package/dist/utils/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/utils/logger.d.mts

@@ -0,0 +1,25 @@
+import debug from 'debug';
+
+/**
+ * Create a namespaced logger for DuckPond
+ *
+ * Usage:
+ *   const log = createLogger('DuckPond')
+ *   log('Initializing...')
+ *
+ * Enable with: DEBUG=duckpond:* node app.js
+ */
+declare function createLogger(namespace: string): debug.Debugger;
+/**
+ * Pre-configured loggers for different modules
+ */
+declare const loggers: {
+    main: debug.Debugger;
+    cache: debug.Debugger;
+    connection: debug.Debugger;
+    query: debug.Debugger;
+    storage: debug.Debugger;
+    metrics: debug.Debugger;
+};
+
+export { createLogger, loggers };

package/dist/utils/logger.d.ts

@@ -0,0 +1,25 @@
+import debug from 'debug';
+
+/**
+ * Create a namespaced logger for DuckPond
+ *
+ * Usage:
+ *   const log = createLogger('DuckPond')
+ *   log('Initializing...')
+ *
+ * Enable with: DEBUG=duckpond:* node app.js
+ */
+declare function createLogger(namespace: string): debug.Debugger;
+/**
+ * Pre-configured loggers for different modules
+ */
+declare const loggers: {
+    main: debug.Debugger;
+    cache: debug.Debugger;
+    connection: debug.Debugger;
+    query: debug.Debugger;
+    storage: debug.Debugger;
+    metrics: debug.Debugger;
+};
+
+export { createLogger, loggers };

package/dist/utils/logger.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkQ6UFPTQCjs = require('../chunk-Q6UFPTQC.js');require('../chunk-5XGN7UAV.js');exports.createLogger = _chunkQ6UFPTQCjs.a; exports.loggers = _chunkQ6UFPTQCjs.b;
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/jordanburke/IdeaProjects/duckpond/dist/utils/logger.js"],"names":[],"mappings":"AAAA,gIAAqC,gCAA6B,gFAAuC","file":"/home/jordanburke/IdeaProjects/duckpond/dist/utils/logger.js"}

package/dist/utils/logger.mjs

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-SZJXSB7U.mjs";import"../chunk-V57JCP3U.mjs";export{a as createLogger,b as loggers};
+//# sourceMappingURL=logger.mjs.map

package/dist/utils/logger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "duckpond",
+  "version": "0.1.0",
+  "description": "Multi-tenant DuckDB manager with R2/S3 storage and functional programming patterns",
+  "keywords": [
+    "duckdb",
+    "r2",
+    "s3",
+    "cloudflare",
+    "multi-tenant",
+    "database",
+    "typescript",
+    "functype",
+    "functional-programming"
+  ],
+  "author": "jordan.burke@gmail.com",
+  "license": "MIT",
+  "homepage": "https://github.com/jordanburke/duckpond",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jordanburke/duckpond"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.38.0",
+    "@types/node": "^22.18.11",
+    "@typescript-eslint/eslint-plugin": "^8.46.1",
+    "@typescript-eslint/parser": "^8.46.1",
+    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "dependencies": {
+    "@duckdb/node-api": "1.4.1-r.4",
+    "@duckdb/node-bindings": "1.4.1-r.4",
+    "debug": "^4.4.3",
+    "functype": "^0.16.0"
+  },
+  "scripts": {
+    "validate": "pnpm format && pnpm lint && pnpm test && pnpm build",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint ./src --fix",
+    "lint:check": "eslint ./src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "build": "rimraf dist && cross-env NODE_ENV=production tsup",
+    "build:watch": "tsup --watch",
+    "dev": "tsup --watch",
+    "ts-types": "tsc"
+  }
+}