@agrodt/astro-redis-cache-provider 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgroDT lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,75 @@
 # @agrodt/astro-redis-cache-provider
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@agrodt/astro-redis-cache-provider`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+[![CI](https://github.com/AgroDT/astro-redis-cache-provider/actions/workflows/ci.yml/badge.svg)](https://github.com/AgroDT/astro-redis-cache-provider/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/AgroDT/astro-redis-cache-provider/badge.svg?branch=main)](https://coveralls.io/github/AgroDT/astro-redis-cache-provider?branch=main)
+[![npm version](https://img.shields.io/npm/v/@agrodt/astro-redis-cache-provider.svg)](https://www.npmjs.com/package/@agrodt/astro-redis-cache-provider)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/@agrodt/astro-redis-cache-provider.svg)](https://www.npmjs.com/package/@agrodt/astro-redis-cache-provider)
+
+Custom Redis cache provider for Astro route caching,
+powered by [`node-redis`](https://github.com/redis/node-redis).
+
+> [!CAUTION]
+> **Disclaimer:** This project is 102% generated by an LLM. The author assumes
+> absolutely no responsibility for any consequences of using it - especially,
+> but not limited to, the mysterious harm that may befall nearby kittens once
+> you deploy this in production. Proceed at your own risk!
+
+## Install
+
+```bash
+pnpm add @agrodt/astro-redis-cache-provider
+```
+
+`node-redis` already comes as a dependency of this package. You only need
+a reachable Redis server.
+
+## Usage
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { redisCache } from "@agrodt/astro-redis-cache-provider/config";
+
+export default defineConfig({
+  experimental: {
+    cache: {
+      provider: redisCache({
+        url: () => process.env.REDIS_URL,
+        keyPrefix: "astro:cache",
+      }),
+    },
+  },
+});
+```
+
+## Options
+
+```ts
+type RedisCacheProviderOptions = {
+  url?: string | (() => string | undefined);
+  keyPrefix?: string;
+  revalidateLockTtl?: number;
+  ignoredVaryHeaders?: Iterable<string>;
+  query?: {
+    include?: string[];
+    exclude?: string[];
+    sort?: boolean;
+  };
+};
+```
+
+- `url`: Redis URL string or runtime factory (`() => string | undefined`),
+  for example `redis://localhost:6379` or `() => process.env.REDIS_URL`.
+- `keyPrefix`: Prefix for all Redis keys. Default: `astro:cache`.
+- `revalidateLockTtl`: Lock lifetime in seconds for stale background
+  revalidation. Default: `30`.
+- `ignoredVaryHeaders`: Additional `Vary` headers to ignore during cache
+  matching (for example `["cookie"]`). `set-cookie` is always ignored.
+- `query`: Same query normalization semantics as Astro memory provider
+  (`include`/`exclude` are mutually exclusive).
+
+## Example
+
+See [example](./example/README.md) for a runnable Astro app that
+demonstrates `MISS`/`HIT` behavior and manual invalidation.

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { CacheProviderConfig } from "astro";
+import type { RedisCacheProviderOptions } from "./runtime.js";
+/**
+ * Creates Astro cache provider configuration for the Redis runtime provider.
+ */
+export declare function redisCache(config?: RedisCacheProviderOptions): CacheProviderConfig<RedisCacheProviderOptions>;
+export default redisCache;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAE9D;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,GAAE,yBAA8B,GACrC,mBAAmB,CAAC,yBAAyB,CAAC,CAMhD;AAED,eAAe,UAAU,CAAC"}

package/dist/config.js

@@ -0,0 +1,12 @@
+/**
+ * Creates Astro cache provider configuration for the Redis runtime provider.
+ */
+export function redisCache(config = {}) {
+    return {
+        name: "redis",
+        entrypoint: "@agrodt/astro-redis-cache-provider/runtime",
+        config,
+    };
+}
+export default redisCache;
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,MAAM,GAA8B,EAAE;IAEtC,OAAO;QACL,IAAI,EAAE,OAAO;QACb,UAAU,EAAE,4CAA4C;QACxD,MAAM;KACP,CAAC;AACJ,CAAC;AAED,eAAe,UAAU,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,74 @@
+import type { CacheProvider } from "astro";
+export type { RedisCacheProvider, RedisCacheProviderOptions };
+export { createRedisCacheProvider, createRedisCacheProvider as default };
+/**
+ * Built-in query parameter patterns excluded from cache keys.
+ * @internal
+ */
+export declare const DEFAULT_EXCLUDED_PARAMS: readonly ["utm_*", "fbclid", "gclid", "gbraid", "wbraid", "dclid", "msclkid", "twclid", "li_fat_id", "mc_cid", "mc_eid", "_ga", "_gl", "_hsenc", "_hsmi", "_ke", "oly_anon_id", "oly_enc_id", "rb_clickid", "s_cid", "vero_id", "wickedid", "yclid", "__s", "ref"];
+/**
+ * Query string normalization settings for cache key generation.
+ *
+ * `include` and `exclude` are mutually exclusive.
+ */
+export interface QueryConfigInput {
+    /**
+     * Only these query parameter names are included in cache keys.
+     * @default undefined
+     */
+    include?: string[];
+    /**
+     * Query parameter names or glob patterns excluded from cache keys.
+     * @default {@link DEFAULT_EXCLUDED_PARAMS}
+     */
+    exclude?: string[];
+    /**
+     * Sorts query parameters before key generation for stable cache keys.
+     * @default true
+     */
+    sort?: boolean;
+}
+/**
+ * Configuration for the Redis cache provider.
+ */
+interface RedisCacheProviderOptions {
+    /**
+     * Redis connection URL or runtime resolver for values unavailable at build time.
+     * @default undefined
+     */
+    url?: string | (() => string | undefined);
+    /**
+     * Prefix used for all cache keys stored in Redis.
+     * @default "astro:cache"
+     */
+    keyPrefix?: string;
+    /**
+     * Query string normalization rules used when building cache keys.
+     * @default undefined
+     */
+    query?: QueryConfigInput;
+    /**
+     * Lock TTL in seconds for stale-while-revalidate background refresh.
+     * @default 30
+     */
+    revalidateLockTtl?: number;
+    /**
+     * Additional `Vary` header names to ignore during cache key matching.
+     * `set-cookie` is always ignored.
+     *
+     * @default []
+     */
+    ignoredVaryHeaders?: Iterable<string>;
+}
+/**
+ * Astro cache provider implementation with an explicit shutdown hook.
+ */
+interface RedisCacheProvider extends CacheProvider {
+    /** Closes the Redis client connection used by the provider instance. */
+    close(): Promise<void>;
+}
+/**
+ * Creates a Redis-backed cache provider for Astro route caching.
+ */
+declare function createRedisCacheProvider(config?: RedisCacheProviderOptions): RedisCacheProvider;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAM3C,YAAY,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,IAAI,OAAO,EAAE,CAAC;AAIzE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,YAClC,OAAO,EACP,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,SAAS,EACT,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,KAAK,EACL,QAAQ,EACR,OAAO,EACP,KAAK,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,UAAU,EACV,OAAO,EACP,KAAK,EACL,KAAK,CACG,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAUD;;GAEG;AACH,UAAU,yBAAyB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAEzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,UAAU,kBAAmB,SAAQ,aAAa;IAChD,wEAAwE;IACxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAqQD;;GAEG;AACH,iBAAS,wBAAwB,CAC/B,MAAM,GAAE,yBAA8B,GACrC,kBAAkB,CAmUpB"}