@ducklings/workers 1.4.3-dev.1 → 1.4.3-dev.2

package/README.md

@@ -35,6 +35,78 @@ export default {
 };
 ```
 
+## Singleton Initialization (Recommended)
+
+For production use, reuse the database and connection across requests to avoid re-initialization overhead:
+
+```typescript
+import { init, DuckDB, type Connection } from '@ducklings/workers';
+import wasmModule from '@ducklings/workers/wasm';
+
+// Global state (reused across requests in the same Worker instance)
+let db: DuckDB | null = null;
+let conn: Connection | null = null;
+let initialized = false;
+
+async function ensureInitialized(): Promise<void> {
+  if (initialized && db && conn) {
+    return;
+  }
+
+  await init({ wasmModule });
+  db = new DuckDB();
+  conn = db.connect();
+  initialized = true;
+}
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    await ensureInitialized();
+
+    const rows = await conn!.query('SELECT 42 as answer');
+    return Response.json(rows);
+  }
+};
+```
+
+## Vite Plugin
+
+For projects using Vite to build Cloudflare Workers, we provide a plugin that handles WASM file resolution and copying:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { ducklingsWorkerPlugin } from '@ducklings/workers/vite-plugin';
+
+export default defineConfig({
+  plugins: [ducklingsWorkerPlugin()],
+  build: {
+    rollupOptions: {
+      external: [/\.wasm$/],
+    },
+  },
+});
+```
+
+### Plugin Options
+
+```typescript
+ducklingsWorkerPlugin({
+  // Output directory for the build (default: 'dist')
+  outDir: 'dist',
+  
+  // Name of the WASM file in the output directory (default: 'duckdb-workers.wasm')
+  wasmFileName: 'duckdb-workers.wasm',
+  
+  // Whether to copy the WASM file to the output directory (default: true)
+  copyWasm: true,
+})
+```
+
+The plugin:
+- Resolves `@ducklings/workers/wasm` imports to a relative path for wrangler
+- Copies the WASM file to your output directory after build
+
 ## Features
 
 - Async API - all query methods return Promises

package/dist/vite-plugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Vite plugin for @ducklings/workers on Cloudflare Workers
+ *
+ * This plugin handles WASM file resolution and copying for Cloudflare Workers deployments.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Vite Plugin interface (minimal definition to avoid hard dependency on vite types)
+ */
+interface VitePlugin {
+    name: string;
+    enforce?: 'pre' | 'post';
+    configResolved?: (config: {
+        root: string;
+    }) => void;
+    resolveId?: (id: string) => {
+        id: string;
+        external: true;
+    } | null;
+    closeBundle?: () => void;
+}
+/**
+ * Configuration options for the Ducklings Workers Vite plugin.
+ */
+interface DucklingsWorkersPluginOptions {
+    /**
+     * Output directory for the build.
+     * @default 'dist'
+     */
+    outDir?: string;
+    /**
+     * Name of the WASM file in the output directory.
+     * @default 'duckdb-workers.wasm'
+     */
+    wasmFileName?: string;
+    /**
+     * Whether to copy the WASM file to the output directory.
+     * Set to false if you handle WASM file copying separately.
+     * @default true
+     */
+    copyWasm?: boolean;
+}
+/**
+ * Resolves the path to the WASM file bundled with @ducklings/workers.
+ *
+ * @returns The absolute path to the WASM file
+ */
+declare function getWasmPath(): string;
+/**
+ * Vite plugin for Cloudflare Workers that handles Ducklings Workers WASM integration.
+ *
+ * This plugin:
+ * - Resolves `@ducklings/workers/wasm` imports to a relative path for wrangler
+ * - Optionally copies the WASM file to your output directory
+ *
+ * @param options - Plugin configuration options
+ * @returns Vite plugin
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { ducklingsWorkerPlugin } from '@ducklings/workers/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [ducklingsWorkerPlugin()],
+ *   build: {
+ *     rollupOptions: {
+ *       external: [/\.wasm$/],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function ducklingsWorkerPlugin(options?: DucklingsWorkersPluginOptions): VitePlugin;
+
+export { type DucklingsWorkersPluginOptions, ducklingsWorkerPlugin as default, ducklingsWorkerPlugin, getWasmPath };

package/dist/vite-plugin.js

@@ -0,0 +1,46 @@
+import { dirname, resolve } from 'path';
+import { mkdirSync, copyFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+// Ducklings Workers - Vite Plugin for Cloudflare Workers
+
+function getWasmPath() {
+  const currentDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(currentDir, "wasm", "duckdb-workers.wasm");
+}
+function ducklingsWorkerPlugin(options = {}) {
+  const { outDir = "dist", wasmFileName = "duckdb-workers.wasm", copyWasm = true } = options;
+  let projectRoot;
+  return {
+    name: "ducklings-workers-plugin",
+    enforce: "pre",
+    configResolved(config) {
+      projectRoot = config.root;
+    },
+    // Resolve WASM imports from the package to relative path
+    resolveId(id) {
+      if (id === "@ducklings/workers/wasm") {
+        return { id: `./${wasmFileName}`, external: true };
+      }
+      return null;
+    },
+    // Copy WASM file to output directory after build
+    closeBundle() {
+      if (!copyWasm) return;
+      const wasmSrcPath = getWasmPath();
+      const wasmDestPath = resolve(projectRoot, outDir, wasmFileName);
+      try {
+        mkdirSync(resolve(projectRoot, outDir), { recursive: true });
+        copyFileSync(wasmSrcPath, wasmDestPath);
+        console.log(`[ducklings] Copied WASM file to ${outDir}/${wasmFileName}`);
+      } catch (e) {
+        console.error("[ducklings] Failed to copy WASM file:", e);
+      }
+    }
+  };
+}
+var vite_plugin_default = ducklingsWorkerPlugin;
+
+export { vite_plugin_default as default, ducklingsWorkerPlugin, getWasmPath };
+//# sourceMappingURL=vite-plugin.js.map
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite-plugin/index.ts"],"names":[],"mappings":";;;;;;AAoDO,SAAS,WAAA,GAAsB;AAEpC,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAC,CAAA;AAEzD,EAAA,OAAO,OAAA,CAAQ,UAAA,EAAY,MAAA,EAAQ,qBAAqB,CAAA;AAC1D;AA4BO,SAAS,qBAAA,CAAsB,OAAA,GAAyC,EAAC,EAAe;AAC7F,EAAA,MAAM,EAAE,MAAA,GAAS,MAAA,EAAQ,eAAe,qBAAA,EAAuB,QAAA,GAAW,MAAK,GAAI,OAAA;AAEnF,EAAA,IAAI,WAAA;AAEJ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,0BAAA;AAAA,IACN,OAAA,EAAS,KAAA;AAAA,IAET,eAAe,MAAA,EAAQ;AACrB,MAAA,WAAA,GAAc,MAAA,CAAO,IAAA;AAAA,IACvB,CAAA;AAAA;AAAA,IAGA,UAAU,EAAA,EAAI;AACZ,MAAA,IAAI,OAAO,yBAAA,EAA2B;AAEpC,QAAA,OAAO,EAAE,EAAA,EAAI,CAAA,EAAA,EAAK,YAAY,CAAA,CAAA,EAAI,UAAU,IAAA,EAAc;AAAA,MAC5D;AACA,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAAA;AAAA,IAGA,WAAA,GAAc;AACZ,MAAA,IAAI,CAAC,QAAA,EAAU;AAEf,MAAA,MAAM,cAAc,WAAA,EAAY;AAChC,MAAA,MAAM,YAAA,GAAe,OAAA,CAAQ,WAAA,EAAa,MAAA,EAAQ,YAAY,CAAA;AAE9D,MAAA,IAAI;AACF,QAAA,SAAA,CAAU,QAAQ,WAAA,EAAa,MAAM,GAAG,EAAE,SAAA,EAAW,MAAM,CAAA;AAC3D,QAAA,YAAA,CAAa,aAAa,YAAY,CAAA;AACtC,QAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,gCAAA,EAAmC,MAAM,CAAA,CAAA,EAAI,YAAY,CAAA,CAAE,CAAA;AAAA,MACzE,SAAS,CAAA,EAAG;AACV,QAAA,OAAA,CAAQ,KAAA,CAAM,yCAAyC,CAAC,CAAA;AAAA,MAC1D;AAAA,IACF;AAAA,GACF;AACF;AAEA,IAAO,mBAAA,GAAQ","file":"vite-plugin.js","sourcesContent":["/**\n * Vite plugin for @ducklings/workers on Cloudflare Workers\n *\n * This plugin handles WASM file resolution and copying for Cloudflare Workers deployments.\n *\n * @packageDocumentation\n */\n\nimport { resolve, dirname } from 'node:path';\nimport { copyFileSync, mkdirSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\n\n/**\n * Vite Plugin interface (minimal definition to avoid hard dependency on vite types)\n */\ninterface VitePlugin {\n  name: string;\n  enforce?: 'pre' | 'post';\n  configResolved?: (config: { root: string }) => void;\n  resolveId?: (id: string) => { id: string; external: true } | null;\n  closeBundle?: () => void;\n}\n\n/**\n * Configuration options for the Ducklings Workers Vite plugin.\n */\nexport interface DucklingsWorkersPluginOptions {\n  /**\n   * Output directory for the build.\n   * @default 'dist'\n   */\n  outDir?: string;\n\n  /**\n   * Name of the WASM file in the output directory.\n   * @default 'duckdb-workers.wasm'\n   */\n  wasmFileName?: string;\n\n  /**\n   * Whether to copy the WASM file to the output directory.\n   * Set to false if you handle WASM file copying separately.\n   * @default true\n   */\n  copyWasm?: boolean;\n}\n\n/**\n * Resolves the path to the WASM file bundled with @ducklings/workers.\n *\n * @returns The absolute path to the WASM file\n */\nexport function getWasmPath(): string {\n  // Get the directory of this module\n  const currentDir = dirname(fileURLToPath(import.meta.url));\n  // WASM file is in the wasm subdirectory relative to dist\n  return resolve(currentDir, 'wasm', 'duckdb-workers.wasm');\n}\n\n/**\n * Vite plugin for Cloudflare Workers that handles Ducklings Workers WASM integration.\n *\n * This plugin:\n * - Resolves `@ducklings/workers/wasm` imports to a relative path for wrangler\n * - Optionally copies the WASM file to your output directory\n *\n * @param options - Plugin configuration options\n * @returns Vite plugin\n *\n * @example\n * ```typescript\n * // vite.config.ts\n * import { defineConfig } from 'vite';\n * import { ducklingsWorkerPlugin } from '@ducklings/workers/vite-plugin';\n *\n * export default defineConfig({\n *   plugins: [ducklingsWorkerPlugin()],\n *   build: {\n *     rollupOptions: {\n *       external: [/\\.wasm$/],\n *     },\n *   },\n * });\n * ```\n */\nexport function ducklingsWorkerPlugin(options: DucklingsWorkersPluginOptions = {}): VitePlugin {\n  const { outDir = 'dist', wasmFileName = 'duckdb-workers.wasm', copyWasm = true } = options;\n\n  let projectRoot: string;\n\n  return {\n    name: 'ducklings-workers-plugin',\n    enforce: 'pre' as const,\n\n    configResolved(config) {\n      projectRoot = config.root;\n    },\n\n    // Resolve WASM imports from the package to relative path\n    resolveId(id) {\n      if (id === '@ducklings/workers/wasm') {\n        // Return external reference that will be resolved at runtime by wrangler\n        return { id: `./${wasmFileName}`, external: true as const };\n      }\n      return null;\n    },\n\n    // Copy WASM file to output directory after build\n    closeBundle() {\n      if (!copyWasm) return;\n\n      const wasmSrcPath = getWasmPath();\n      const wasmDestPath = resolve(projectRoot, outDir, wasmFileName);\n\n      try {\n        mkdirSync(resolve(projectRoot, outDir), { recursive: true });\n        copyFileSync(wasmSrcPath, wasmDestPath);\n        console.log(`[ducklings] Copied WASM file to ${outDir}/${wasmFileName}`);\n      } catch (e) {\n        console.error('[ducklings] Failed to copy WASM file:', e);\n      }\n    },\n  };\n}\n\nexport default ducklingsWorkerPlugin;\n"]}

package/dist/wasm.d.ts

@@ -0,0 +1,3 @@
+// Type declaration for the DuckDB WASM module
+declare const wasmModule: WebAssembly.Module;
+export default wasmModule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducklings/workers",
-  "version": "1.4.3-dev.1",
+  "version": "1.4.3-dev.2",
   "description": "Minimal DuckDB WASM for Cloudflare Workers and serverless environments",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,8 +12,15 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./wasm": "./dist/wasm/duckdb-workers.wasm",
-    "./wasm/*": "./dist/wasm/*"
+    "./wasm": {
+      "types": "./dist/wasm.d.ts",
+      "default": "./dist/wasm/duckdb-workers.wasm"
+    },
+    "./wasm/*": "./dist/wasm/*",
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js"
+    }
   },
   "files": [
     "dist",
@@ -21,7 +28,7 @@
   ],
   "scripts": {
     "build": "tsup && pnpm postbuild",
-    "postbuild": "mkdir -p dist/wasm && cp ../../dist/duckdb-workers.js dist/wasm/ && cp ../../dist/duckdb-workers.wasm dist/wasm/",
+    "postbuild": "mkdir -p dist/wasm && cp ../../dist/duckdb-workers.js dist/wasm/ && cp ../../dist/duckdb-workers.wasm dist/wasm/ && cp src/wasm.d.ts dist/wasm.d.ts",
     "dev": "tsup --watch",
     "test": "vitest run --reporter=dot",
     "test:watch": "vitest --reporter=dot",
@@ -46,6 +53,14 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
   },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "keywords": [
     "duckdb",
     "wasm",