Kg non standard environment examples (#43)

added cloudflare & nextjs examples (will add more in future) in `examples/` subdir to showcase usage of `astra-db-ts` on non-standard environments

Author: toptobes

README.md

@@ -356,3 +356,5 @@ so you'll need to set it explicitly if you want to use the native fetch implemen
 On some environments, such as Cloudflare Workers, you may additionally need to use the events
 polyfill for the client to work properly (i.e. `npm i events`). Cloudflare's node-compat won't
 work here.
+
+Check out the `examples/` subdirectory for some non-standard runtime examples with more info.

examples/cloudflare-workers/.dev.vars.example

@@ -0,0 +1,5 @@
+# Your Astra DB token (AstraCS:...)
+ASTRA_DB_TOKEN=
+
+# Your Astra DB ID (https://<id>-<region>.apps.astra.datastax.com)
+ASTRA_DB_ENDPOINT=

examples/cloudflare-workers/.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
+
+.dev.vars
+.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/

examples/cloudflare-workers/README.md

@@ -0,0 +1,74 @@
+# astra-db-ts w/ Cloudflare Workers
+
+## Overview
+
+`astra-db-ts` works nearly natively with the Cloudflare Workers runtime. The only detour required
+to make this work is to install the `events` polyfill, which is not included natively in the
+Workers runtime. Luckily, this is as simple as doing `npm i events` in your project.
+
+This is a simple example of how it can be used to interact with an Astra database; it'll simply
+list out all the collections in a given database.
+
+Check out the [Non-standard runtime support](../../README.md#non-standard-runtime-support) section
+in the main `README.md` for more information common between non-standard runtimes.
+
+## Getting started
+
+### Prerequisites:
+
+- Make sure you have an existing Astra Database running @ [astra.datastax.com](https://astra.datastax.com/).
+  - You'll need an API key and a database endpoint URL to get started.
+
+### How to use this example:
+
+1. Clone this repository to your local machine.
+
+2. Run `npm install` to install the required dependencies.
+
+3. Copy the `.dev.vars.example` file to `.dev.vars` and fill in the required values.
+
+4. Run `npm run dev` to start the local development server.
+
+5. Visit `http://localhost:8787` in your browser to see the example in action (or just press `b`).
+
+### Steps to start your own project:
+
+1. Use the typical `npm create cloudflare@latest` to create a new Cloudflare Workers project.
+
+2. Install `@datastax/astra-db-ts` and `events` by running `npm i @datastax/astra-db-ts events`.
+
+3. You should be able to use `@datastax/astra-db-ts` in your project as normal now.
+
+## Full code sample
+
+```ts
+import { DataAPIClient } from '@datastax/astra-db-ts';
+
+export interface Env {
+  ASTRA_DB_TOKEN: string,
+  ASTRA_DB_ENDPOINT: string,
+}
+
+export default {
+  async fetch(_req: Request, env: Env, _ctx: ExecutionContext): Promise<Response> {
+    // Creates the client. `astra-db-ts` can automatically infer that it should be using
+    // the native `fetch` client under the hood for you.
+    const client = new DataAPIClient(env.ASTRA_DB_TOKEN);
+    const db = client.db(env.ASTRA_DB_ENDPOINT);
+
+    // Simple example which (attempts to) list all the collections in the database
+    try {
+      const collections = await db.listCollections();
+
+      return new Response(JSON.stringify(collections), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (error: any) {
+      return new Response(JSON.stringify({ error: error.message }), {
+        headers: { 'Content-Type': 'application/json' },
+        status: 500,
+      });
+    }
+  },
+};
+```