Create strong-mice-dance.md

.changeset/strong-mice-dance.md

@@ -0,0 +1,5 @@
+---
+"@llamaindex/env": patch
+---
+
+fix: async local storage on cloudflare worker

apps/next/src/content/docs/llamaindex/setup/cloudflare.mdx

@@ -37,6 +37,33 @@ Then, you need create `.dev.vars` and add LLM api keys for the local development
 
 <Callout type="warn">Do not commit the api key to git repository.</Callout>
 
+## Integrating with Hono
+
+```ts
+import { Hono } from "hono";
+
+type Bindings = {
+  OPENAI_API_KEY: string;
+};
+
+const app = new Hono<{
+  Bindings: Bindings;
+}>();
+
+app.post("/llm", async (c) => {
+  const { setEnvs } = await import("@llamaindex/env");
+  setEnvs(c.env);
+
+  // ...
+
+  return new Response('Hello, world!');
+})
+
+export default {
+  fetch: app.fetch,
+};
+```
+
 ## Difference between Node.js and Cloudflare Worker
 
 In Cloudflare Worker and similar serverless JS environment, you need to be aware of the following differences:
@@ -46,3 +73,7 @@ In Cloudflare Worker and similar serverless JS environment, you need to be aware
 - Some of LlamaIndex.TS modules are not available in Cloudflare Worker, for example `SimpleDirectoryReader` (requires `node:fs`), Some multimodal API that relies on [`onnxruntime-node`](https://www.npmjs.com/package/onnxruntime-node)(we might port to HTTP based module in the future).
 - `@llamaindex/core` is designed to work in all JavaScript environment, including Cloudflare Worker. If you find any issue, please report to us.
 - `@llamaindex/env` is a JS environment binding module, which polyfill some Node.js/Modern Web API (for example, we have a memory based `fs` module, and Crypto API polyfill). It is designed to work in all JavaScript environment, including Cloudflare Worker.
+
+## Known issues
+
+- `llamaindex` not work perfectly in Cloudflare Worker, bundle size will be larger than 1MB, which is the limit of Cloudflare Worker. You will need import submodule instead of the whole `llamaindex` module.

e2e/examples/cloudflare-hono/.gitignore

@@ -0,0 +1,172 @@
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+# wrangler project
+
+.dev.vars
+.wrangler/

e2e/examples/cloudflare-hono/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@llamaindex/cloudflare-hono",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "deploy": "wrangler deploy",
+    "build": "wrangler deploy --dry-run --outdir dist",
+    "dev": "wrangler dev",
+    "start": "wrangler dev",
+    "cf-typegen": "wrangler types"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241112.0",
+    "typescript": "^5.5.2",
+    "wrangler": "^3.89.0"
+  },
+  "dependencies": {
+    "hono": "^4.6.11"
+  }
+}

e2e/examples/cloudflare-hono/src/index.ts

@@ -0,0 +1,91 @@
+import { Hono } from "hono";
+
+type Bindings = {
+  OPENAI_API_KEY: string;
+  PINECONE_API_KEY: string;
+};
+
+const app = new Hono<{
+  Bindings: Bindings;
+}>();
+
+app.post("/llm", async (c) => {
+  //#region init envs
+  const { setEnvs } = await import("@llamaindex/env");
+  setEnvs(c.env);
+  //#endregion
+
+  const { message } = await c.req.json();
+
+  const { extractText } = await import("@llamaindex/core/utils");
+
+  const {
+    QueryEngineTool,
+    serviceContextFromDefaults,
+    VectorStoreIndex,
+    OpenAIAgent,
+    Settings,
+    OpenAI,
+    OpenAIEmbedding,
+  } = await import("llamaindex");
+
+  const { PineconeVectorStore } = await import(
+    "llamaindex/vector-store/PineconeVectorStore"
+  );
+
+  const llm = new OpenAI({
+    model: "gpt-4o-mini",
+    apiKey: c.env.OPENAI_API_KEY,
+  });
+
+  Settings.embedModel = new OpenAIEmbedding({
+    model: "text-embedding-3-small",
+    apiKey: c.env.OPENAI_API_KEY,
+  });
+
+  const serviceContext = serviceContextFromDefaults({
+    llm,
+    chunkSize: 8191,
+    chunkOverlap: 0,
+  });
+
+  const store = new PineconeVectorStore({
+    namespace: "8xolsn4ulEQGdhnhP76yCzfLHdOZ",
+  });
+
+  const index = await VectorStoreIndex.fromVectorStore(store, serviceContext);
+
+  const retriever = index.asRetriever({
+    similarityTopK: 3,
+  });
+
+  // Create a query engine
+  const queryEngine = index.asQueryEngine({
+    retriever,
+  });
+
+  const tools = [
+    new QueryEngineTool({
+      queryEngine: queryEngine,
+      metadata: {
+        name: "business_info_tool",
+        description:
+          "This tool can answer questions based " +
+          "on business information. Return not found if you" +
+          " can't find the answer in the documents.",
+      },
+    }),
+  ];
+
+  const agent = new OpenAIAgent({ tools });
+
+  const response = await agent.chat({
+    message: message,
+  });
+
+  return new Response(extractText(response.message.content));
+});
+
+export default {
+  fetch: app.fetch,
+};

e2e/examples/cloudflare-hono/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+
+    /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "target": "es2021",
+    /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+    "lib": ["es2021", "DOM.AsyncIterable"],
+    /* Specify what JSX code is generated. */
+    "jsx": "react-jsx",
+    /* Specify what module code is generated. */
+    "module": "es2022",
+    /* Specify how TypeScript looks up a file from a given module specifier. */
+    "moduleResolution": "Bundler",
+    /* Specify type package names to be included without being referenced in a source file. */
+    "types": ["@cloudflare/workers-types/2023-07-01"],
+    /* Enable importing .json files */
+    "resolveJsonModule": true,
+    /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */
+    "allowJs": true,
+    /* Enable error reporting in type-checked JavaScript files. */
+    "checkJs": false,
+    /* Disable emitting files from a compilation. */
+    "noEmit": true,
+    /* Ensure that each file can be safely transpiled without relying on other imports. */
+    "isolatedModules": true,
+    /* Allow 'import x from y' when a module doesn't have a default export. */
+    "allowSyntheticDefaultImports": true,
+    /* Ensure that casing is correct in imports. */
+    "forceConsistentCasingInFileNames": true,
+    /* Enable all strict type-checking options. */
+    "strict": true,
+    /* Skip type checking all .d.ts files. */
+    "skipLibCheck": true
+  },
+  "exclude": ["test"],
+  "include": ["vitest.config.mts", "worker-configuration.d.ts", "src/**/*.ts"]
+}

e2e/examples/cloudflare-hono/worker-configuration.d.ts

@@ -0,0 +1,4 @@
+// Generated by Wrangler by running `wrangler types`
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+interface Env {}

e2e/examples/cloudflare-hono/wrangler.toml

@@ -0,0 +1,7 @@
+name = "llamaindex-cloudflare-hono-example"
+main = "src/index.ts"
+compatibility_date = "2024-11-12"
+compatibility_flags = ["nodejs_als"]
+
+[observability]
+enabled = true

packages/env/src/als/index.workerd.ts

@@ -0,0 +1 @@
+export { AsyncLocalStorage } from "node:async_hooks";

packages/env/src/index.workerd.ts

@@ -7,7 +7,7 @@
  */
 import { INTERNAL_ENV } from "./utils/index.js";
 
-export * from "./als/index.non-node.js";
+export * from "./als/index.workerd.js";
 export { NotSupportCurrentRuntimeClass } from "./utils/shared.js";
 
 export * from "./node-polyfill.js";

pnpm-lock.yaml

@@ -380,6 +380,22 @@ importers:
         specifier: ^4.19.0
         version: 4.19.2
 
+  e2e/examples/cloudflare-hono:
+    dependencies:
+      hono:
+        specifier: ^4.6.11
+        version: 4.6.11
+    devDependencies:
+      '@cloudflare/workers-types':
+        specifier: ^4.20241112.0
+        version: 4.20241112.0
+      typescript:
+        specifier: ^5.5.2
+        version: 5.6.3
+      wrangler:
+        specifier: ^3.89.0
+        version: 3.89.0(@cloudflare/workers-types@4.20241112.0)(bufferutil@4.0.8)
+
   e2e/examples/cloudflare-worker-agent:
     dependencies:
       llamaindex:
@@ -8284,6 +8300,10 @@ packages:
   hoist-non-react-statics@3.3.2:
     resolution: {integrity: sha512-/gGivxi8JPKWNm/W0jSmzcMPpfpPLc3dY/6GxhX2hQ9iGj3aDfklV4ET7NjKpSinLpJ5vafa9iiGIEZg10SfBw==}
 
+  hono@4.6.11:
+    resolution: {integrity: sha512-f0LwJQFKdUUrCUAVowxSvNCjyzI7ZLt8XWYU/EApyeq5FfOvHFarBaE5rjU9HTNFk4RI0FkdB2edb3p/7xZjzQ==}
+    engines: {node: '>=16.9.0'}
+
   hono@4.6.9:
     resolution: {integrity: sha512-p/pN5yZLuZaHzyAOT2nw2/Ud6HhJHYmDNGH6Ck1OWBhPMVeM1r74jbCRwNi0gyFRjjbsGgoHbOyj7mT1PDNbTw==}
     engines: {node: '>=16.9.0'}
@@ -9682,6 +9702,11 @@ packages:
     engines: {node: '>=16.13'}
     hasBin: true
 
+  miniflare@3.20241106.1:
+    resolution: {integrity: sha512-dM3RBlJE8rUFxnqlPCaFCq0E7qQqEQvKbYX7W/APGCK+rLcyLmEBzC4GQR/niXdNM/oV6gdg9AA50ghnn2ALuw==}
+    engines: {node: '>=16.13'}
+    hasBin: true
+
   minimalistic-assert@1.0.1:
     resolution: {integrity: sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==}
 
@@ -12574,6 +12599,9 @@ packages:
   unenv-nightly@2.0.0-20241024-111401-d4156ac:
     resolution: {integrity: sha512-xJO1hfY+Te+/XnfCYrCbFbRcgu6XEODND1s5wnVbaBCkuQX7JXF7fHEXPrukFE2j8EOH848P8QN19VO47XN8hw==}
 
+  unenv-nightly@2.0.0-20241111-080453-894aa31:
+    resolution: {integrity: sha512-0W39QQOQ9VE8kVVUpGwEG+pZcsCXk5wqNG6rDPE6Gr+fiA69LR0qERM61hW5KCOkC1/ArCFrfCGjwHyyv/bI0Q==}
+
   unicode-canonical-property-names-ecmascript@2.0.1:
     resolution: {integrity: sha512-dA8WbNeb2a6oQzAQ55YlT5vQAWGV9WXOsi3SskE3bcCdM0P4SDd+24zS/OCacdRq5BkdsRj9q3Pg6YyQoxIGqg==}
     engines: {node: '>=4'}
@@ -13113,6 +13141,16 @@ packages:
       '@cloudflare/workers-types':
         optional: true
 
+  wrangler@3.89.0:
+    resolution: {integrity: sha512-ix3Rir/cu9Cn6FklvPDIW1QwOMcRU8iPj3IrkBWGdB66K9z1uqyqoTP64UZZyXrBItfrU7SbQT4L5wJ5y10TPA==}
+    engines: {node: '>=16.17.0'}
+    hasBin: true
+    peerDependencies:
+      '@cloudflare/workers-types': ^4.20241106.0
+    peerDependenciesMeta:
+      '@cloudflare/workers-types':
+        optional: true
+
   wrap-ansi@6.2.0:
     resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
     engines: {node: '>=8'}
@@ -22118,6 +22156,8 @@ snapshots:
     dependencies:
       react-is: 16.13.1
 
+  hono@4.6.11: {}
+
   hono@4.6.9: {}
 
   hpack.js@2.1.6:
@@ -23988,6 +24028,25 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  miniflare@3.20241106.1(bufferutil@4.0.8):
+    dependencies:
+      '@cspotcode/source-map-support': 0.8.1
+      acorn: 8.14.0
+      acorn-walk: 8.3.4
+      capnp-ts: 0.7.0
+      exit-hook: 2.2.1
+      glob-to-regexp: 0.4.1
+      stoppable: 1.1.0
+      undici: 5.28.4
+      workerd: 1.20241106.1
+      ws: 8.18.0(bufferutil@4.0.8)
+      youch: 3.3.4
+      zod: 3.23.8
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
   minimalistic-assert@1.0.1: {}
 
   minimatch@10.0.1:
@@ -27290,6 +27349,13 @@ snapshots:
       pathe: 1.1.2
       ufo: 1.5.4
 
+  unenv-nightly@2.0.0-20241111-080453-894aa31:
+    dependencies:
+      defu: 6.1.4
+      ohash: 1.1.4
+      pathe: 1.1.2
+      ufo: 1.5.4
+
   unicode-canonical-property-names-ecmascript@2.0.1: {}
 
   unicode-emoji-modifier-base@1.0.0: {}
@@ -28024,6 +28090,35 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  wrangler@3.89.0(@cloudflare/workers-types@4.20241112.0)(bufferutil@4.0.8):
+    dependencies:
+      '@cloudflare/kv-asset-handler': 0.3.4
+      '@cloudflare/workers-shared': 0.7.1
+      '@esbuild-plugins/node-globals-polyfill': 0.2.3(esbuild@0.17.19)
+      '@esbuild-plugins/node-modules-polyfill': 0.2.2(esbuild@0.17.19)
+      blake3-wasm: 2.1.5
+      chokidar: 4.0.1
+      date-fns: 4.1.0
+      esbuild: 0.17.19
+      itty-time: 1.0.6
+      miniflare: 3.20241106.1(bufferutil@4.0.8)
+      nanoid: 3.3.7
+      path-to-regexp: 6.3.0
+      resolve: 1.22.8
+      resolve.exports: 2.0.2
+      selfsigned: 2.4.1
+      source-map: 0.6.1
+      unenv: unenv-nightly@2.0.0-20241111-080453-894aa31
+      workerd: 1.20241106.1
+      xxhash-wasm: 1.0.2
+    optionalDependencies:
+      '@cloudflare/workers-types': 4.20241112.0
+      fsevents: 2.3.3
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
   wrap-ansi@6.2.0:
     dependencies:
       ansi-styles: 4.3.0

tsconfig.json

@@ -74,6 +74,9 @@
     {
       "path": "./e2e/examples/cloudflare-worker-agent/tsconfig.json"
     },
+    {
+      "path": "./e2e/examples/cloudflare-hono/tsconfig.json"
+    },
     {
       "path": "./e2e/examples/nextjs-agent/tsconfig.json"
     },