@studiocms/cfetch 0.2.0 → 0.3.0

package/README.md

@@ -103,10 +103,19 @@ interface CachedResponse<T> {
 
 ```ts
 interface CFetchConfig {
-    ttl?: Duration.DurationInput;
-    tags?: string[];
-    key?: string;
-    verbose?: boolean;
+  ttl?: Duration.DurationInput;
+  tags?: string[];
+  key?: string;
+  verbose?: boolean;
+}
+```
+
+##### `InvalidateCacheOptions` type
+
+```ts
+interface InvalidateCacheOptions {
+	keys?: string[];
+	tags?: string[];
 }
 ```
 
@@ -140,6 +149,27 @@ Return type:
 */
 ```
 
+##### `invalidateCacheEffect`
+
+###### Interface
+
+```ts
+const invalidateCacheEffect: (opts: InvalidateCacheOptions) => Effect.Effect<void, never, never>
+```
+
+###### Example Usage
+
+```ts
+const effect = invalidateCacheEffect({
+  tags: ['user'],
+  keys: ['user:123', 'user:456']
+})
+/*
+Return type:
+  Effect.Effect<void, never, never>
+*/
+```
+
 ##### `cFetchEffectJson`
 
 ###### Interface
@@ -247,7 +277,7 @@ const cFetch: <T>(
 ```ts
 import { cFetch } from "c:fetch"
 
-const effect = await cFetch<{ foo: string; bar: number; }>(
+const response = await cFetch<{ foo: string; bar: number; }>(
   'https://api.example.com/data',
   (res) => res.json(),
   { method: "GET" }
@@ -275,7 +305,7 @@ const cFetchJson: <T>(
 ```ts
 import { cFetchJson } from "c:fetch"
 
-const effect = await cFetchJson<{ foo: string; bar: number; }>(
+const response = await cFetchJson<{ foo: string; bar: number; }>(
   'https://api.example.com/data',
   { method: "GET" }
 );
@@ -302,7 +332,7 @@ const cFetchText: (
 ```ts
 import { cFetchText } from "c:fetch"
 
-const effect = await cFetchText(
+const response = await cFetchText(
   'https://example.com',
   { method: "GET" }
 );
@@ -329,7 +359,7 @@ const cFetchBlob: (
 ```ts
 import { cFetchBlob } from "c:fetch"
 
-const effect = await cFetchBlob(
+const response = await cFetchBlob(
   'https://example.com/image.png',
   { method: "GET" }
 );
@@ -339,6 +369,27 @@ Return type:
 */
 ```
 
+##### `invalidateCache`
+
+###### Interface
+
+```ts
+const invalidateCache: (opts: InvalidateCacheOptions) => Promise<void>
+```
+
+###### Example Usage
+
+```ts
+const res = await invalidateCache({
+  tags: ['user'],
+  keys: ['user:123', 'user:456']
+})
+/*
+Return type:
+  void
+*/
+```
+
 ## Licensing
 
 [MIT Licensed](https://github.com/withstudiocms/cfetch/blob/main/LICENSE).

package/dist/{cache.d.ts → cache.d.mts}

@@ -1,47 +1,44 @@
-/**
- * @module cfetch/cache
- * Cache service implementation using Effect-TS.
- */
-import { Context, Duration, Effect } from 'effect';
+import { Context, Duration, Effect } from "effect";
+
+//#region src/cache.d.ts
 /**
  * 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>;
+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>;
+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>>;
+  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 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>;
+  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.
@@ -73,6 +70,6 @@ declare const CacheService_base: Effect.Service.Class<CacheService, "@studiocms/
  *
  * @public
  */
-export declare class CacheService extends CacheService_base {
-}
-export {};
+declare class CacheService extends CacheService_base {}
+//#endregion
+export { CacheEntry, CacheEntryStatus, CacheMaps, CacheService };

package/dist/cache.mjs

@@ -0,0 +1,176 @@
+import { defaultConfigLive } from "./consts.mjs";
+import { Clock, Context, Duration, Effect } from "effect";
+
+//#region src/cache.ts
+/**
+* @module cfetch/cache
+* Cache service implementation using Effect-TS.
+*/
+/**
+* Tag to hold the in-memory cache maps.
+*
+* This tag provides access to the main cache store and the tag index for invalidation.
+*/
+var CacheMaps = class extends Context.Tag("@studiocms/cfetch/CacheMaps")() {};
+/**
+* Error thrown when there is an issue fetching the cache configuration.
+*/
+var ConfigFetchError = class {
+	_tag = "ConfigFetchError";
+};
+/**
+* Fetches the cache configuration from the virtual module.
+* Falls back to default configuration if not available.
+*/
+const getConfig = async () => {
+	try {
+		return (await import("virtual:cfetch/config")).default;
+	} catch (error) {
+		console.warn("Could not load virtual:cfetch/config, using default config.");
+		return defaultConfigLive;
+	}
+};
+/**
+* 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
+*/
+var CacheService = class extends Effect.Service()("@studiocms/cfetch/CacheService", { effect: Effect.gen(function* () {
+	const { store, tagIndex } = yield* CacheMaps;
+	/**
+	* Get the Cache Configuration from the virtual module, with a fallback to default configuration.
+	*
+	* This function attempts to load the cache configuration from the virtual module `virtual:cfetch/config`. If the module is not available or fails to load, it catches the error and returns a default configuration. This ensures that the cache service always has a valid configuration to work with, even in environments where the virtual module cannot be resolved.
+	*
+	* @returns {import('virtual:cfetch/config').CacheConfigLive} The cache configuration object
+	* @throws {ConfigFetchError} If there is an error fetching the configuration
+	*/
+	const config = yield* Effect.tryPromise({
+		try: () => getConfig(),
+		catch: () => new ConfigFetchError()
+	}).pipe(Effect.catchTag("ConfigFetchError", () => Effect.succeed(defaultConfigLive)));
+	/**
+	* Retrieves a value from the cache by its key, checking for expiration and returning null if the entry is not found or has expired.
+	*
+	* @template A - The type of the cached value
+	* @param key - The key associated with the cached entry
+	* @returns An Effect that yields the cached value of type A, or null if not found or expired
+	*/
+	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;
+	});
+	/**
+	* Sets a value in the cache with an optional TTL and tags for invalidation.
+	*
+	* This function adds a new entry to the cache with the specified key and value. It calculates the expiration time based on the provided TTL (or the default lifetime from the configuration) and associates any provided tags with the entry for later invalidation. If tags are provided, it also updates the tag index to allow for efficient invalidation of entries by tag.
+	*
+	* @template A - The type of the value being cached
+	* @param key - The key to associate with the cached entry
+	* @param value - The value to cache
+	* @param options - Optional configuration for the cache entry, including TTL and tags
+	*/
+	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);
+		}
+	});
+	/**
+	* Deletes a cache entry by its key, removing it from the cache and updating the tag index accordingly.
+	*
+	* This function removes a cache entry identified by the given key from the main cache store. If the entry exists, it also iterates through the associated tags and updates the tag index to remove references to the deleted key. If a tag no longer has any keys associated with it after deletion, the tag is removed from the index entirely.
+	*
+	* @param key - The key of the cache entry to delete
+	* @returns An Effect that performs the deletion when executed
+	*/
+	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);
+		}
+	});
+	/**
+	* Invalidates cache entries based on specified tags, removing all entries associated with those tags from the cache.
+	*
+	* This function takes an array of tags and iterates through each tag to find all associated cache keys from the tag index. It then deletes each of those keys from the cache using the `deleteKey` function. This allows for efficient batch invalidation of cache entries that are grouped by common tags.
+	*
+	* @param tags - An array of tags for which to invalidate associated cache entries
+	* @returns An Effect that performs the invalidation when executed
+	*/
+	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);
+		}
+	});
+	/**
+	* Clears the entire cache, removing all entries and resetting the tag index.
+	*
+	* This function completely empties the cache store and the tag index, effectively resetting the cache to an empty state. It is useful for scenarios where a full cache reset is needed, such as during development or when significant changes occur that invalidate all cached data.
+	*
+	* @returns An Effect that performs the cache clearing when executed
+	*/
+	const clear = () => Effect.sync(() => {
+		store.clear();
+		tagIndex.clear();
+	});
+	return {
+		get,
+		set,
+		delete: deleteKey,
+		invalidateTags,
+		clear
+	};
+}) }) {};
+
+//#endregion
+export { CacheMaps, CacheService };

package/dist/consts.d.mts

@@ -0,0 +1,17 @@
+import { CacheConfig, CacheConfigLive } from "./types.mjs";
+
+//#region src/consts.d.ts
+/**
+ * Default cache configuration for cfetch.
+ *
+ * This configuration sets the default lifetime of cached entries to 1 hour.
+ */
+declare const defaultConfig: CacheConfig;
+/**
+ * Default cache configuration with live values for internal use.
+ *
+ * This configuration converts the lifetime to milliseconds for use in caching logic.
+ */
+declare const defaultConfigLive: CacheConfigLive;
+//#endregion
+export { defaultConfig, defaultConfigLive };

package/dist/consts.mjs

@@ -0,0 +1,23 @@
+import { Duration } from "effect";
+
+//#region src/consts.ts
+/**
+* @module cfetch/consts
+*
+* Constant values used throughout the cfetch package.
+*/
+/**
+* Default cache configuration for cfetch.
+*
+* This configuration sets the default lifetime of cached entries to 1 hour.
+*/
+const defaultConfig = { lifetime: Duration.hours(1) };
+/**
+* Default cache configuration with live values for internal use.
+*
+* This configuration converts the lifetime to milliseconds for use in caching logic.
+*/
+const defaultConfigLive = { lifetime: Duration.toMillis(Duration.hours(1)) };
+
+//#endregion
+export { defaultConfig, defaultConfigLive };

package/dist/index.d.mts

@@ -0,0 +1,32 @@
+import { CacheConfig } from "./types.mjs";
+import { Duration } from "effect";
+import { AstroIntegration } from "astro";
+
+//#region src/index.d.ts
+/**
+ * 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)
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+declare function cFetch(opts?: CacheConfig): AstroIntegration;
+//#endregion
+export { Duration, cFetch, cFetch as default };

package/dist/index.mjs

@@ -0,0 +1,62 @@
+import { defaultConfig } from "./consts.mjs";
+import { addVirtualImports, createResolver } from "./utils/integration.mjs";
+import stub_default from "./stub.mjs";
+import { Duration, Duration as Duration$1 } from "effect";
+
+//#region src/index.ts
+/**
+* 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)
+*     })
+*   ]
+* });
+* ```
+*/
+function cFetch(opts) {
+	const name = "@studiocms/cfetch";
+	const { resolve } = createResolver(import.meta.url);
+	const options = {
+		...defaultConfig,
+		...opts
+	};
+	return {
+		name,
+		hooks: {
+			"astro:config:setup": (params) => {
+				addVirtualImports(params, {
+					name,
+					imports: {
+						"virtual:cfetch/config": `export default ${JSON.stringify({ lifetime: Duration$1.toMillis(options.lifetime) })}`,
+						"c:fetch": `export * from '${resolve("./wrappers.mjs")}';`
+					}
+				});
+			},
+			"astro:config:done": ({ injectTypes }) => {
+				injectTypes({
+					filename: "cfetch.d.ts",
+					content: stub_default
+				});
+			}
+		}
+	};
+}
+var src_default = cFetch;
+
+//#endregion
+export { Duration, cFetch, src_default as default };

package/dist/stub.d.mts

@@ -0,0 +1,22 @@
+//#region src/stub.d.ts
+/**
+ * This file serves as a stub for TypeScript type definitions related to the cFetch integration.
+ * It defines the structure of virtual modules and the types that will be injected into the consuming project.
+ * The actual implementation of these types is provided in the corresponding .mjs files, but this stub allows
+ * for proper type checking and IntelliSense in development environments.
+ *
+ * The stub includes module declarations for 'virtual:cfetch/config' and 'c:fetch', defining the expected types
+ * and exports that will be available when using the cFetch integration in an Astro project.
+ *
+ * @remarks
+ * - The 'virtual:cfetch/config' module provides access to the cache configuration, which can be customized by users.
+ * - The 'c:fetch' module exports various types and functions related to the cached fetch functionality, including error types, parsers, and the main cFetch function.
+ *
+ * @module
+ */
+/**
+ * Stub content for TypeScript type definitions related to the cFetch integration.
+ */
+declare const stub: string;
+//#endregion
+export { stub as default };