@studiocms/cfetch 0.1.5 → 0.2.0

package/README.md

@@ -17,7 +17,7 @@ This is an [Astro integration](https://docs.astro.build/en/guides/integrations-g
 
 ### Installation
 
-Install the integration **automatically** using the Astro CLI:
+1. Install the integration **automatically** using the Astro CLI:
 
 ```bash
 pnpm astro add @studiocms/cfetch
@@ -47,7 +47,23 @@ npm install @studiocms/cfetch
 yarn add @studiocms/cfetch
 ```
 
-2. Add the integration to your astro config
+2. Install peer dependencies
+
+If your package manager does not automatically install peer dependencies, you will need to ensure `Effect` is installed.
+
+```bash
+pnpm add effect
+```
+
+```bash
+npm install effect
+```
+
+```bash
+yarn add effect
+```
+
+3. Add the integration to your astro config
 
 ```diff
 +import cFetch from "@studiocms/cfetch";
@@ -61,39 +77,266 @@ export default defineConfig({
 
 ### Usage
 
-You can import the `cFetch` function anywhere and use it as you would use a normal `fetch` call. `cFetch` adapts the same default options as `fetch`:
+This integration includes various versions of cached fetch functions and [Effects](https://effect.website) to allow full control of how you work with your data.
+
+#### Effects
+
+All Effects have the following return pattern or derivatives there of
+
+```ts
+Effect.Effect<CachedResponse<T>, FetchError, never>;
+```
+
+##### `CachedResponse<T>` type
+
+```ts
+interface CachedResponse<T> {
+  data: T;
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+```
+
+##### `CFetchConfig` type
+
+```ts
+interface CFetchConfig {
+    ttl?: Duration.DurationInput;
+    tags?: string[];
+    key?: string;
+    verbose?: boolean;
+}
+```
+
+##### `cFetchEffect`
+
+###### Interface
+
+```ts
+const cFetchEffect: <T>(
+  url: string | URL, 
+  parser: (response: Response) => Promise<T>, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Effect.Effect<CachedResponse<T>, FetchError, never>
+```
+
+###### Example Usage
+
+```ts
+import { cFetchEffect, Duration } from "c:fetch"
+
+const effect = cFetchEffect<{ foo: string; bar: number; }>(
+  'https://api.example.com/data',
+  (res) => res.json(),
+  { method: "GET" },
+  { ttl?: Duration.hours(1), tags?: ['example'], key?: "api-data-fetch", verbose?: false }
+);
+/*
+Return type:
+  Effect.Effect<CachedResponse<{ foo: string; bar: number; }>, FetchError, never>
+*/
+```
+
+##### `cFetchEffectJson`
+
+###### Interface
+
+```ts
+const cFetchEffectJson: <T>(
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Effect.Effect<CachedResponse<T>, FetchError, never>
+```
+
+###### Example Usage
+
+```ts
+import { cFetchEffectJson } from "c:fetch"
+
+const effect = cFetchEffectJson<{ foo: string; bar: number; }>(
+  'https://api.example.com/data',
+  { method: "GET" }
+);
+/*
+Return type:
+  Effect.Effect<CachedResponse<{ foo: string; bar: number; }>, FetchError, never>
+*/
+```
+
+##### `cFetchEffectText`
+
+###### Interface
+
+```ts
+const cFetchEffectText: (
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Effect.Effect<CachedResponse<string>, FetchError, never>
+```
+
+###### Example Usage
 
-```astro
----
-import { cFetch } from 'c:fetch';
+```ts
+import { cFetchEffectText } from "c:fetch"
 
-const response = await cFetch(
-    'https://example.com', // string | URL | Request
-    { /* Normal fetch init optional options here, method, mode, etc. */ },
-    { lifetime: "1h" }, // Optional, allows changing the default lifetime of the cache
-    'json', // Optional, allows changing the type of response object to be cached. 'json' (default) or 'text'
+const effect = cFetchEffectText(
+  'https://example.com',
+  { method: "GET" }
 );
+/*
+Return type:
+  Effect.Effect<CachedResponse<string>, FetchError, never>
+*/
+```
+
+##### `cFetchEffectBlob`
+
+###### Interface
+
+```ts
+const cFetchEffectBlob: (
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Effect.Effect<CachedResponse<Blob>, FetchError, never>
+```
+
+###### Example Usage
+
+```ts
+import { cFetchEffectBlob } from "c:fetch"
+
+const effect = cFetchEffectBlob(
+  'https://example.com/image.png',
+  { method: "GET" }
+);
+/*
+Return type:
+  Effect.Effect<CachedResponse<Blob>, FetchError, never>
+*/
+```
 
-const html = await response.text();
----
+#### Functions
+
+All Functions have the following return pattern or derivatives there of
+
+```ts
+CachedResponse<T>;
+```
+
+##### `cFetch`
+
+###### Interface
+
+```ts
+const cFetch: <T>(
+  url: string | URL, 
+  parser: (response: Response) => Promise<T>, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Promise<CachedResponse<T>>
 ```
 
-If you need to access the other available metadata (such as the `lastChecked` value which provides the last time the cache was updated), you can pass `true` as the fourth parameter, which will change the returned object to the following:
+###### Example Usage
 
-```astro
----
-import { cFetch } from 'c:fetch';
+```ts
+import { cFetch } from "c:fetch"
 
-const { lastCheck, data } = await cFetch(
-    'https://example.com',
-    { /* ... */ },
-    { lifetime: "1h" },
-    'json',
-    true // Changes the the output to include the lastCheck value
+const effect = await cFetch<{ foo: string; bar: number; }>(
+  'https://api.example.com/data',
+  (res) => res.json(),
+  { method: "GET" }
 );
+/*
+Return type:
+  CachedResponse<{ foo: string; bar: number; }>
+*/
+```
+
+##### `cFetchJson`
+
+###### Interface
+
+```ts
+const cFetchJson: <T>(
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Promise<CachedResponse<T>>
+```
 
-const html = await data.text();
----
+###### Example Usage
+
+```ts
+import { cFetchJson } from "c:fetch"
+
+const effect = await cFetchJson<{ foo: string; bar: number; }>(
+  'https://api.example.com/data',
+  { method: "GET" }
+);
+/*
+Return type:
+  CachedResponse<{ foo: string; bar: number; }>
+*/
+```
+
+##### `cFetchText`
+
+###### Interface
+
+```ts
+const cFetchText: (
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Promise<CachedResponse<string>>
+```
+
+###### Example Usage
+
+```ts
+import { cFetchText } from "c:fetch"
+
+const effect = await cFetchText(
+  'https://example.com',
+  { method: "GET" }
+);
+/*
+Return type:
+  CachedResponse<string>
+*/
+```
+
+##### `cFetchBlob`
+
+###### Interface
+
+```ts
+const cFetchBlob: (
+  url: string | URL, 
+  options?: RequestInit | undefined, 
+  cacheConfig?: CFetchConfig | undefined
+) => Promise<CachedResponse<Blob>>
+```
+
+###### Example Usage
+
+```ts
+import { cFetchBlob } from "c:fetch"
+
+const effect = await cFetchBlob(
+  'https://example.com/image.png',
+  { method: "GET" }
+);
+/*
+Return type:
+  CachedResponse<Blob>
+*/
 ```
 
 ## Licensing

package/dist/cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module cfetch/cache
+ * Cache service implementation using Effect-TS.
+ */
+import { Context, Duration, Effect } from 'effect';
+/**
+ * Represents a cache entry with its value, expiration time, last updated time, and tags.
+ */
+export interface CacheEntry<A> {
+    value: A;
+    expiresAt: number;
+    lastUpdatedAt: number;
+    tags: Set<string>;
+}
+/**
+ * Represents the status of a cache entry, including expiration and tags.
+ */
+export interface CacheEntryStatus {
+    expiresAt: Date;
+    lastUpdatedAt: Date;
+    tags: Set<string>;
+}
+declare const CacheMaps_base: Context.TagClass<CacheMaps, "@studiocms/cfetch/CacheMaps", {
+    store: Map<string, CacheEntry<unknown>>;
+    tagIndex: Map<string, Set<string>>;
+}>;
+/**
+ * Tag to hold the in-memory cache maps.
+ *
+ * This tag provides access to the main cache store and the tag index for invalidation.
+ */
+export declare class CacheMaps extends CacheMaps_base {
+}
+declare const CacheService_base: Effect.Service.Class<CacheService, "@studiocms/cfetch/CacheService", {
+    readonly effect: Effect.Effect<{
+        get: <A>(key: string) => Effect.Effect<A | null, never, never>;
+        set: <A>(key: string, value: A, options?: {
+            ttl?: Duration.DurationInput;
+            tags?: string[];
+        }) => Effect.Effect<void, never, never>;
+        delete: (key: string) => Effect.Effect<void, never, never>;
+        invalidateTags: (tags: string[]) => Effect.Effect<void, never, never>;
+        clear: () => Effect.Effect<void, never, never>;
+    }, never, CacheMaps>;
+}>;
+/**
+ * A service for managing cached data with TTL (time-to-live) and tag-based invalidation.
+ *
+ * @remarks
+ * This service provides an in-memory cache with the following features:
+ * - Automatic expiration based on TTL
+ * - Tag-based organization for batch invalidation
+ * - Effect-based API for safe side-effect management
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService;
+ *
+ *   // Set a value with custom TTL and tags
+ *   yield* cache.set('user:123', userData, {
+ *     ttl: Duration.minutes(5),
+ *     tags: ['user', 'profile']
+ *   });
+ *
+ *   // Get a value
+ *   const result = yield* cache.get('user:123');
+ *
+ *   // Invalidate all entries with specific tags
+ *   yield* cache.invalidateTags(['user']);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class CacheService extends CacheService_base {
+}
+export {};

package/dist/cache.js

@@ -0,0 +1,89 @@
+import { Clock, Context, Duration, Effect } from "effect";
+import { defaultConfigLive } from "./consts";
+class CacheMaps extends Context.Tag("@studiocms/cfetch/CacheMaps")() {
+}
+class ConfigFetchError {
+  _tag = "ConfigFetchError";
+}
+const getConfig = async () => {
+  try {
+    const config = await import("virtual:cfetch/config");
+    return config.default;
+  } catch (error) {
+    console.warn("Could not load virtual:cfetch/config, using default config.");
+    return defaultConfigLive;
+  }
+};
+class CacheService extends Effect.Service()("@studiocms/cfetch/CacheService", {
+  effect: Effect.gen(function* () {
+    const { store, tagIndex } = yield* CacheMaps;
+    const config = yield* Effect.tryPromise({
+      try: () => getConfig(),
+      catch: () => new ConfigFetchError()
+    }).pipe(Effect.catchTag("ConfigFetchError", () => Effect.succeed(defaultConfigLive)));
+    const get = (key) => Effect.gen(function* () {
+      const now = yield* Clock.currentTimeMillis;
+      const entry = store.get(key);
+      if (!entry) return null;
+      if (entry.expiresAt < now) {
+        yield* deleteKey(key);
+        return null;
+      }
+      return entry.value;
+    });
+    const set = (key, value, options) => Effect.gen(function* () {
+      const now = yield* Clock.currentTimeMillis;
+      const ttl = options?.ttl ?? Duration.millis(config.lifetime);
+      const tags = new Set(options?.tags ?? []);
+      const expiresAt = now + Duration.toMillis(ttl);
+      store.set(key, { value, expiresAt, lastUpdatedAt: now, tags });
+      for (const tag of tags) {
+        if (!tagIndex.has(tag)) {
+          tagIndex.set(tag, /* @__PURE__ */ new Set());
+        }
+        tagIndex.get(tag)?.add(key);
+      }
+    });
+    const deleteKey = (key) => Effect.sync(() => {
+      const entry = store.get(key);
+      if (entry) {
+        for (const tag of entry.tags) {
+          const keys = tagIndex.get(tag);
+          if (keys) {
+            keys.delete(key);
+            if (keys.size === 0) {
+              tagIndex.delete(tag);
+            }
+          }
+        }
+        store.delete(key);
+      }
+    });
+    const invalidateTags = (tags) => Effect.gen(function* () {
+      for (const tag of tags) {
+        const keys = tagIndex.get(tag);
+        if (keys) {
+          for (const key of [...keys]) {
+            yield* deleteKey(key);
+          }
+        }
+      }
+    });
+    const clear = () => Effect.sync(() => {
+      store.clear();
+      tagIndex.clear();
+    });
+    return {
+      get,
+      set,
+      delete: deleteKey,
+      invalidateTags,
+      clear
+    };
+  })
+}) {
+}
+export {
+  CacheMaps,
+  CacheService
+};

package/dist/consts.d.ts

@@ -1,12 +1,8 @@
 /**
- * This module contains constants for cFetch
- * @module
- */
-import type { CacheConfig } from './types.js';
-/**
- * Default cache configuration object.
+ * @module cfetch/consts
  *
- * @property {string} lifetime - The duration for which the cache is valid.
- *                               Accepts a string representation of time, e.g., '1h' for 1 hour.
+ * Constant values used throughout the cfetch package.
  */
+import type { CacheConfig, CacheConfigLive } from './types.js';
 export declare const defaultConfig: CacheConfig;
+export declare const defaultConfigLive: CacheConfigLive;

package/dist/consts.js

@@ -1,6 +1,11 @@
+import { Duration } from "effect";
 const defaultConfig = {
-  lifetime: "1h"
+  lifetime: Duration.hours(1)
+};
+const defaultConfigLive = {
+  lifetime: Duration.toMillis(Duration.hours(1))
 };
 export {
-  defaultConfig
+  defaultConfig,
+  defaultConfigLive
 };

package/dist/index.d.ts

@@ -1,38 +1,65 @@
 /**
- * This module contains the AstroIntegration for cFetch
- * @module
- */
-import type { AstroIntegration } from 'astro';
-import type { CacheConfig } from './types.js';
-/**
- * Astro integration that allows you to have a cached fetch function in your Astro SSR project.
+ * @module @studiocms/cfetch
  *
- * This integration will add a virtual import for `cached:fetch` that you can use in your components.
+ * An Astro integration that provides a caching fetch utility using Effect.
  *
- * @returns {AstroIntegration} The integration object for Astro
- * @see {@link https://github.com/withstudiocms/cfetch} for more details
- * @example
- * ```typescript
+ * This module exports the `cFetch` function, which can be used to create an Astro
+ * integration that adds virtual modules for cached fetching capabilities. It also
+ * exports the `Duration` type from Effect for specifying cache lifetimes.
+ *
+ * The `cFetch` integration injects virtual modules:
+ * - `virtual:cfetch/config`: Exports the default cache configuration.
+ * - `c:fetch`: Exports various cached fetch functions and types.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * import cFetch, { Duration } from '@studiocms/cfetch';
  * import { defineConfig } from 'astro/config';
- * import cFetch from '@studiocms/cfetch';
  *
  * export default defineConfig({
  *   integrations: [
  *     cFetch({
- * 	     lifetime: '1h', // OPTIONAL Cache lifetime, can be '<number>m' or '<number>h'
- *     })
+ *       lifetime: Duration.minutes(5), // Set cache lifetime to 5 minutes (default is 1 hour)
+ *     }),
  *   ],
  * });
  * ```
  *
- * then in your components you can use:
+ * You can then use the cached fetch functions in your Astro components or pages:
  *
- * ```typescript
+ * ```ts
  * import { cFetch } from 'c:fetch';
  *
- * const response = await cFetch('https://example.com/api/data');
- * const data = await response.json();
- * // Use the data in your component
+ * const response = await cFetch('https://api.example.com/data', (res) => res.json());
+ * console.log(response.data);
+ * ```
+ */
+import type { AstroIntegration } from 'astro';
+import type { CacheConfig } from './types.js';
+export { Duration } from 'effect';
+/**
+ * Creates a caching fetch integration for Astro.
+ *
+ * This integration provides a cached fetch implementation that can be configured
+ * with custom cache lifetime and other options. It sets up virtual module imports
+ * and injects TypeScript type definitions for the cached fetch functionality.
+ *
+ * @param opts - Optional cache configuration options to customize the caching behavior
+ * @returns An Astro integration object with hooks for configuration setup and completion
+ *
+ * @example
+ * ```typescript
+ * // astro.config.mjs
+ * import cFetch, { Duration } from '@studiocms/cfetch';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     cFetch({
+ *       lifetime: Duration.minutes(10), // Cache entries live for 10 minutes (default is 1 hour)
+ *     })
+ *   ]
+ * });
  * ```
  */
 export declare function cFetch(opts?: CacheConfig): AstroIntegration;

package/dist/index.js

@@ -1,6 +1,8 @@
+import { Duration } from "effect";
 import { defaultConfig } from "./consts.js";
 import stub from "./stub.js";
 import { addVirtualImports, createResolver } from "./utils/integration.js";
+import { Duration as Duration2 } from "effect";
 function cFetch(opts) {
   const name = "@studiocms/cfetch";
   const { resolve } = createResolver(import.meta.url);
@@ -15,7 +17,10 @@ function cFetch(opts) {
         addVirtualImports(params, {
           name,
           imports: {
-            "virtual:cfetch/config": `export default ${JSON.stringify(options)}`,
+            "virtual:cfetch/config": `export default ${JSON.stringify({
+              // Convert Duration.DurationInput to milliseconds number (required to preserve value through JSON.stringify)
+              lifetime: Duration.toMillis(options.lifetime)
+            })}`,
             "c:fetch": `export * from '${resolve("./wrappers.js")}';`
           }
         });
@@ -31,6 +36,7 @@ function cFetch(opts) {
 }
 var index_default = cFetch;
 export {
+  Duration2 as Duration,
   cFetch,
   index_default as default
 };