@edgefirst-dev/core NPM

@edgefirst-dev/core

The core of the Edge-first Stack.

Installation

bun add @edgefirst-dev/core

Usage

In your Cloudflare Worker, call the bootstrap function and export it.

import schema from "db:schema";
import { bootstrap } from "@edgefirst-dev/core/worker";

export default bootstrap({
  orm: { schema },

  rateLimit: { limit: 1000, period: 60 },

  jobs() {
    // Register your jobs here
    return [];
  },

  tasks() {
    // Schedule your tasks here
    return [];
  }

  async onRequest(request) {
    return new Response("Hello, World!", { status: 200 });
  },

  async onSchedule() {
    // Add your scheduled tasks here
  },
});

async function getLoadContext(request: Request) {
  let ua = UserAgent.fromRequest(request);
  let ip = IPAddress.fromRequest(request);
  return { ua, ip };
}

declare module "@edgefirst-dev/core" {
  export interface Bindings {
    // Add your custom bindings here
  }

  type Schema = typeof schema;
  export interface DatabaseSchema extends Schema {}
}

Now you can import the functions from @edgefirst-dev/core and use it in any part of your Remix app.

env()

The env function gives you access to the environment variables in a type-safe way.

import { env } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the env object.

Env#fetch

The env().fetch method is used to get a value from the environment variables.

The function expects the environment variable name. If the environment variable is not set and no fallback is provided, it will throw an EdgeEnvKeyError.

let CLIENT_ID = env().fetch("CLIENT_ID");

There's a second optional parameter that can be used as a fallback value if the environment variable is not set.

let SESSION_SECRET = env().fetch("SESSION_SECRET", "fallback");

kv()

The kv function gives you access to a Key-Value store powered by Cloudflare Worker KV.

import { kv } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the KV object.

KV#keys

The kv().keys method is used to get a list of keys in the store.

The function returns an object with the keys, a cursor to get the next page, and a boolean to know if there are more keys to fetch.

// Get a list of keys
let { keys, cursor, done } = await kv().keys();

In case done is true ther cursor will be null. Otherwise it will be a string that can be used to get the next page of keys.

let { keys, cursor, done } = await kv().keys({ cursor });

Additionally, a prefix can be provided to filter the keys.

let { keys, cursor, done } = await kv().keys("prefix", { cursor });

KV#get

The kv().get method is used to get a single key from the store.

The function returns an object with the data and metadata of the key.

let { data, meta } = await kv().get("prefix:key");

KV#set

The kv().set method is used to save a key in the store.

The function expects the key, the value, and an optional object with the TTL and metadata.

await kv().set("prefix:key", value, { ttl: 3600, metadata: { key: "value" } });

KV#has

The kv().has method is used to check if a key is stored.

The function returns a boolean indicating if the key is stored.

let hasKey = await kv().has("prefix:key");

KV#remove

The kv().remove method is used to remove a key from the store.

await kv().remove("prefix:key");

KV#binding

A read-only property that gives you the KVNamespace used by the KV object.

let namespace = kv().binding;

!TIP The namespace can be used to access the KVNamespace directly in case you need to integrate with it.

fs()

The fs function gives you an instance of @mjackson/file-storage powered by Cloudflare R2.

import { fs } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the FS object.
!TIP Check @mjackson's File Storage documentation to know what's possible with this library. The FS#keys and FS#serve methods are not available in the original library, they are custom methods added by this library and therefore are documented here.

FS#keys

The fs().keys method is used to get a list of keys in the store.

let { keys, cursor, done } = await fs().keys();

FS#serve

The fs().serve method is used to get a response object that can be sent to the browser with the file data.

let response = await fs().serve("key");

FS#uploadHandler

The fs().uploadHandler method is used to create a handler that can be used to upload files to the store.

import { parseFormData } from "@mjackson/form-data-parser";

let formData = await parseFormData(request, fs().uploadHandler(["avatar"]));

The uploadHandler method expects an array of keys that will be used to store the files. Optionally, a function can be provided to get the key from the file.

let formData = await parseFormData(
  request,
  fs().uploadHandler(["avatar"], (file) => {
    return `avatar:${file.name}`;
  })
);

FS#binding

A read-only property that gives you the R2Bucket used by the FS object.

let bucket = fs().binding;

!TIP The bucket can be used to access the R2 bucket directly in case you need to integrate with it.

db()

The db function gives you access to a database object powered by Cloudflare D1.

import { db as edgeDb } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the database.

This object is compatible with D1 interface so it can be used with Drizzle ORM or any other D1 compatible library.

import { drizzle } from "drizzle-orm/d1";
import * as schema from "~/db/schema";

export const db = drizzle(edgeDb(), { schema });
export { schema };

DB#binding

A read-only property that gives you the D1Database used by the database object.

let database = db().binding;

!TIP The database can be used to access the D1 database directly in case you need to integrate with it.

orm()

The orm function gives you access to a database object powered by Cloudflare D1 and Drizzle ORM.

import { orm } from "@edgefirst-dev/core";

!WARN This function is memoized, so the next time you call it, it will return the same instance of the Drizzle ORM, the memoization is not taking into account the arguments of the functions.

cache()

The cache function gives you access to a cache object powered by Cloudflare Worker KV.

import { cache } from "@edgefirst-dev/core";

Every cached key will be prefixed by cache: to avoid conflicts with other keys.

!WARNING This function is memoized so the next time you call it, it will return the same instance of the cache object.

Cache#fetch

The cache().fetch method is used to get a value from the cache or calculate it if it's not there.

The function expects the key, the TTL, and a function that will be called to calculate the value if it's not in the cache.

let ONE_HOUR_IN_SECONDS = 3600;

let value = await cache().fetch("key", ONE_HOUR_IN_SECONDS, async () => {
  // do something expensive and return the value
});

The TTL is optional, it defaults to 60 seconds if not provided.

await cache().fetch("another-key", async () => {
  // The TTL is optional, it defaults to 60 seconds
});

Cache#purge

The cache().purge method is used to remove a key from the cache.

cache().purge("key");

Cache#binding

A read-only property that gives you the KVNamespace used by the Cache object.

let namespace = cache().binding;

!TIP The namespace can be used to access the KVNamespace directly in case you need to integrate with it.

request()

The request function gives you access to the current request object.

import { request } from "@edgefirst-dev/core";

let url = new URL(request().url);
request().headers.get("Authorization");

headers()

The headers function gives you access to the current request headers using @mjackson/headers.

!TIP Check @mjackson's Headers documentation to know what's possible with this library.

import { headers } from "@edgefirst-dev/core";

headers().cacheControl.maxAge;
// And other properties of the library

signal()

The signal function gives you access to the current request signal.

import { signal } from "@edgefirst-dev/core";
signal().aborted;

ai

The ai object gives you access to the AI services powered by Cloudflare AI.

import { ai } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the AI object.
!IMPORTANT This marked as unstable because it's still in development and the API might change.

AI#textToImage

The ai().textToImage method is used to generates images from input text. These models can be used to generate and modify images based on text prompts

let output = await ai().textToImage(model, inputs, options);

AI#imageToText

The ai().imageToText method is used to output a text from a given image. Image captioning or optical character recognition can be considered as the most common applications of image to text

await ai().imageToText(model, inputs, options);

AI#translation

The ai().translation method is used to convert a sequence of text from one language to another.

await ai().translation(model, inputs, options);

AI#summarization

The ai().summarization method is used to produce a shorter version of a document while preserving its important information.

await ai().summarization(model, inputs, options);

AI#textEmbeddings

The ai().textEmbeddings method is used to transform raw data into numerical features that can be processed while preserving the information in the original dataset.

await ai().textEmbeddings(model, inputs, options);

AI#textGeneration

The ai().textGeneration method is used to generate text based on a given prompt.

await ai().textGeneration(model, inputs, options);

AI#objectDetection

The ai().objectDetection method is used to detect instances of objects like persons, faces, license plates, or others in an image.

await ai().objectDetection(model, inputs, options);

AI#speechRecognition

The ai().speechRecognition method is used to convert a speech signal, typically an audio input, to text.

await ai().speechRecognition(model, inputs, options);

AI#textClassification

The ai().textClassification method is used to classify a text input into labels or classes.

await ai().textClassification(model, inputs, options);

AI#imageClassification

The ai().imageClassification method is used to classify an image input into labels or classes.

await ai().imageClassification(model, inputs, options);

AI#binding

A read-only property that gives you the Cloudflare Ai object used by the AI object.

let service = ai().binding;

!TIP The service can be used to access the AIService directly in case you need to integrate with it.

queue

The queue object gives you access to a Queue publisher powered by Cloudflare Queue.

import { queue } from "@edgefirst-dev/core";

!WARNING This function is memoized so the next time you call it, it will return the same instance of the queue object.
!IMPORTANT This marked as unstable because it's still in development and the API might change.

Queue#enqueue

The queue().enqueue method is used to enqueue a payload in the queue.

await queue().enqueue(payload, options);

Queue#binding

A read-only property that gives you the Cloudflare Queue object used by the Queue object.

let queue = queue().binding;

!TIP The queue can be used to access the Queue directly in case you need to integrate with it.

geo

The geo object gives you access to the geolocation data powered by Cloudflare CDN.

import { geo } from "@edgefirst-dev/core";

This function returns an object with the geolocation data. The object conforms to the interface:

interface Geo {
  country: Iso3166Alpha2Code | "T1";
  region: string;
  city: string;
  postalCode: string;
  latitude: string;
  longitude: string;
  timezone: string;
  metroCode: string;
  continent: ContinentCode;
  isEurope: boolean;
}

!TIP The Iso3166Alpha2Code and ContinentCode are union types provided by Cloudflare Worker types package.

rateLimit

The rateLimit object gives you access to the rate limiting object powered by Cloudflare Worker KV.

import { rateLimit } from "@edgefirst-dev/core";

!WARNING This function is not memoized so the next time you call it, it will return a new instance of the rate limit object.
!IMPORTANT This marked as experimental because it's still in development and the API might change.

RateLimit#limit

The rateLimit().limit method is used to limit the number of requests per key.

await rateLimit().limit({ key });

RateLimit#reset

The rateLimit().reset method is used to reset the rate limit for a key.

await rateLimit().reset({ key });

RateLimit#writeHttpMetadata

The rateLimit().writeHttpMetadata method is used to write the rate limit metadata to the response headers.

await rateLimit().writeHttpMetadata({ key }, headers);

Errors

The library may throw some errors, they can all be imported so you can handle them.

import {
  EdgeConfigError,
  EdgeContextError,
  EdgeEnvKeyError,
  EdgeRequestGeoError,
} from "@edgefirst-dev/core";

Override Bindings

You can override the bindings by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

declare module "@edgefirst-dev/core" {
  interface Bindings {
    // Add your custom bindings here
  }
}

If you're using wrangler types to generate the types, you can make Bindings extends the interface generated by wrangler types.

Override Database Schema

Similarly, you can override the database schema by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

import type * as schema from "~/db/schema"; // Your DB schema

declare module "@edgefirst-dev/core" {
  interface DatabaseSchema extends schema {}
}