@ez4/cache 0.42.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silas B.
+
+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

@@ -0,0 +1,64 @@
+# EZ4: Cache
+
+It uses the power of [reflection](../../foundation/reflection/) to provide a contract that determines how to build and connect cache components.
+
+## Getting started
+
+#### Install
+
+```sh
+npm install @ez4/cache @ez4/local-cache @ez4/aws-valkey -D
+```
+
+#### Create cache
+
+```ts
+// file: cache.ts
+import type { Environment, Service } from '@ez4/common';
+import type { Cache } from '@ez4/email';
+
+// MyCache declaration
+export declare class MyCache extends Cache.Service {
+  engine: Cache.UseEngine<{
+    name: 'valkey
+  }>
+}
+```
+
+#### Use cache
+
+```ts
+// file: handler.ts
+import type { Service } from '@ez4/common';
+import type { MyCache } from './cache';
+
+// Any other handler that has injected MyCache service
+export async function anyHandler(_request: any, context: Service.Context<DummyService>) {
+  const { myCache } = context;
+
+  await myCache.set('key', 'value');
+
+  const value = myCache.get('key');
+}
+```
+
+## Cache properties
+
+#### Service
+
+| Name   | Type              | Description                              |
+| ------ | ----------------- | ---------------------------------------- |
+| engine | Cache.UseEngine<> | Determines which database engine to use. |
+
+## Examples
+
+- [Get started with cache](../../examples/hello-aws-cache)
+
+## Providers
+
+- [AWS provider](../../providers/aws/aws-valkey)
+- [Local provider](../../providers/local/local-cache)
+
+## License
+
+MIT License

package/dist/errors/engine.d.ts

@@ -0,0 +1,11 @@
+import { IncompleteTypeError, IncorrectTypeError, InvalidTypeError } from '@ez4/common/library';
+export declare class IncompleteEngineError extends IncompleteTypeError {
+    constructor(properties: string[], fileName?: string);
+}
+export declare class InvalidEngineTypeError extends InvalidTypeError {
+    constructor(fileName?: string);
+}
+export declare class IncorrectEngineTypeError extends IncorrectTypeError {
+    engineType: string;
+    constructor(engineType: string, fileName?: string);
+}

package/dist/errors/service.d.ts

@@ -0,0 +1,4 @@
+import { IncompleteTypeError } from '@ez4/common/library';
+export declare class IncompleteServiceError extends IncompleteTypeError {
+    constructor(properties: string[], fileName?: string);
+}

package/dist/library.cjs

@@ -0,0 +1,40 @@
+"use strict";var h=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var L=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var n=(e,r)=>h(e,"name",{value:r,configurable:!0});var W=(e,r)=>{for(var t in r)h(e,t,{get:r[t],enumerable:!0})},q=(e,r,t,s)=>{if(r&&
+typeof r=="object"||typeof r=="function")for(let i of L(r))!H.call(e,i)&&i!==t&&
+h(e,i,{get:()=>r[i],enumerable:!(s=A(r,i))||s.enumerable});return e};var F=e=>q(h({},"__esModule",{value:!0}),e);var J={};W(J,{IncompleteEngineError:()=>d,IncompleteServiceError:()=>g,IncorrectEngineTypeError:()=>v,
+InvalidEngineTypeError:()=>y,ServiceType:()=>u,createCacheService:()=>b,getCacheEngineMetadata:()=>S,
+getCacheServicesMetadata:()=>x,getLinkedService:()=>E,isCacheEngineDeclaration:()=>z,
+isCacheService:()=>V,isCacheServiceDeclaration:()=>T,registerTriggers:()=>G});module.
+exports=F(J);var O=require("@ez4/common/library"),P=require("@ez4/project/library");var o=require("@ez4/common/library"),j=require("@ez4/reflection"),D=require("@ez4/utils");var M=require("@ez4/common/library");var g=class extends M.IncompleteTypeError{static{n(this,"IncompleteServiceError")}constructor(r,t){
+super("Incomplete cache service",r,t)}};var f=require("@ez4/reflection"),w=require("@ez4/utils"),c=require("@ez4/common/library");var l=require("@ez4/common/library");var d=class extends l.IncompleteTypeError{static{n(this,"IncompleteEngineError")}constructor(r,t){
+super("Incomplete cache engine",r,t)}},y=class extends l.InvalidTypeError{static{
+n(this,"InvalidEngineTypeError")}constructor(r){super("Invalid cache engine type",
+void 0,"Cache.Engine",r)}},v=class extends l.IncorrectTypeError{constructor(t,s){
+super("Incorrect cache engine type",t,"Cache.Engine",s);this.engineType=t}static{
+n(this,"IncorrectEngineTypeError")}};var z=n(e=>(0,c.hasHeritageType)(e,"Cache.Engine"),"isCacheEngineDeclaration"),S=n(
+(e,r,t,s)=>{if(!(0,f.isTypeReference)(e))return I(e,r,s);let i=(0,c.getReferenceType)(
+e,t);if(i)return I(i,r,s)},"getCacheEngineMetadata"),N=n(e=>(0,w.isObjectWith)(e,
+["name"]),"isCompleteEngine"),I=n((e,r,t)=>{if((0,f.isTypeObject)(e))return k(e,
+r,(0,c.getObjectMembers)(e),t);if(!(0,c.isModelDeclaration)(e)){t.push(new y(r.file));
+return}if(!z(e)){t.push(new v(e.name,e.file));return}return k(e,r,(0,c.getModelMembers)(
+e),t)},"getTypeEngine"),k=n((e,r,t,s)=>{let i={},a=new Set(["name"]);for(let p of t)
+if(!(!(0,f.isModelProperty)(p)||p.inherited))switch(p.name){default:{s.push(new c.InvalidServicePropertyError(
+r.name,p.name,e.file));break}case"name":{(i.name=(0,c.getPropertyString)(p))&&a.
+delete(p.name);break}}if(!N(i)){s.push(new d([...a],e.file));return}return i},"g\
+etTypeFromMembers");var R=require("@ez4/project/library");var u="@ez4/cache",V=n(e=>e.type===u,"isCacheService"),b=n(e=>({...(0,R.createServiceMetadata)(
+u,e),variables:{},services:{}}),"createCacheService");var T=n(e=>(0,o.isClassDeclaration)(e)&&(0,o.hasHeritageType)(e,"Cache.Service"),
+"isCacheServiceDeclaration"),x=n(e=>{let r={},t=[];for(let s in e){let i=e[s];if(!T(
+i)||(0,o.isExternalDeclaration)(i))continue;let a=b(i.name),p=new Set(["engine"]),
+C=i.file;i.description&&(a.description=i.description);for(let m of(0,o.getModelMembers)(
+i))if((0,j.isModelProperty)(m))switch(m.name){default:{t.push(new o.InvalidServicePropertyError(
+a.name,m.name,C));break}case"client":break;case"engine":{(a.engine=S(m.value,i,e,
+t))&&p.delete(m.name);break}case"variables":{a.variables=(0,o.getLinkedVariableList)(
+m,t);break}case"services":{a.services=(0,o.getLinkedServiceList)(m,e,t);break}}if(!B(
+a)){t.push(new g([...p],C));continue}if(r[i.name]){t.push(new o.DuplicateServiceError(
+i.name,C));continue}r[i.name]=a}return{services:r,errors:t}},"getCacheServicesMe\
+tadata"),B=n(e=>(0,D.isObjectWith)(e,["engine","variables","services"]),"isCompl\
+eteService");var E=n(e=>T(e)?e.name:null,"getLinkedService");var G=n(()=>{(0,O.registerTriggers)(),(0,P.tryCreateTrigger)(u,{"metadata:getSer\
+vices":x,"metadata:getLinkedService":E})},"registerTriggers");0&&(module.exports={IncompleteEngineError,IncompleteServiceError,IncorrectEngineTypeError,
+InvalidEngineTypeError,ServiceType,createCacheService,getCacheEngineMetadata,getCacheServicesMetadata,
+getLinkedService,isCacheEngineDeclaration,isCacheService,isCacheServiceDeclaration,
+registerTriggers});
+//# sourceMappingURL=library.cjs.map

package/dist/library.d.ts

@@ -0,0 +1,7 @@
+export * from './triggers/register';
+export * from './triggers/service';
+export * from './errors/service';
+export * from './errors/engine';
+export * from './metadata/service';
+export * from './metadata/engine';
+export * from './metadata/types';

package/dist/library.mjs

@@ -0,0 +1,33 @@
+var b=Object.defineProperty;var r=(e,i)=>b(e,"name",{value:i,configurable:!0});import{registerTriggers as _}from"@ez4/common/library";import{tryCreateTrigger as $}from"@ez4/project/library";import{DuplicateServiceError as N,InvalidServicePropertyError as V,isExternalDeclaration as B,
+isClassDeclaration as G,getLinkedServiceList as J,getLinkedVariableList as K,getModelMembers as Q,
+hasHeritageType as U}from"@ez4/common/library";import{isModelProperty as X}from"@ez4/reflection";
+import{isObjectWith as Y}from"@ez4/utils";import{IncompleteTypeError as x}from"@ez4/common/library";var p=class extends x{static{r(this,"IncompleteServiceError")}constructor(i,t){super(
+"Incomplete cache service",i,t)}};import{isModelProperty as k,isTypeObject as w,isTypeReference as z}from"@ez4/reflection";
+import{isObjectWith as R}from"@ez4/utils";import{InvalidServicePropertyError as j,
+isModelDeclaration as D,getModelMembers as O,getObjectMembers as P,getPropertyString as A,
+getReferenceType as L,hasHeritageType as H}from"@ez4/common/library";import{IncompleteTypeError as E,IncorrectTypeError as M,InvalidTypeError as I}from"@ez4/common/library";var m=class extends E{static{r(this,"IncompleteEngineError")}constructor(i,t){super(
+"Incomplete cache engine",i,t)}},l=class extends I{static{r(this,"InvalidEngineT\
+ypeError")}constructor(i){super("Invalid cache engine type",void 0,"Cache.Engine",
+i)}},f=class extends M{constructor(t,c){super("Incorrect cache engine type",t,"C\
+ache.Engine",c);this.engineType=t}static{r(this,"IncorrectEngineTypeError")}};var W=r(e=>H(e,"Cache.Engine"),"isCacheEngineDeclaration"),h=r((e,i,t,c)=>{if(!z(
+e))return v(e,i,c);let n=L(e,t);if(n)return v(n,i,c)},"getCacheEngineMetadata"),
+q=r(e=>R(e,["name"]),"isCompleteEngine"),v=r((e,i,t)=>{if(w(e))return u(e,i,P(e),
+t);if(!D(e)){t.push(new l(i.file));return}if(!W(e)){t.push(new f(e.name,e.file));
+return}return u(e,i,O(e),t)},"getTypeEngine"),u=r((e,i,t,c)=>{let n={},o=new Set(
+["name"]);for(let s of t)if(!(!k(s)||s.inherited))switch(s.name){default:{c.push(
+new j(i.name,s.name,e.file));break}case"name":{(n.name=A(s))&&o.delete(s.name);break}}
+if(!q(n)){c.push(new m([...o],e.file));return}return n},"getTypeFromMembers");import{createServiceMetadata as F}from"@ez4/project/library";var g="@ez4/cache",de=r(e=>e.type===g,"isCacheService"),T=r(e=>({...F(g,e),variables:{},
+services:{}}),"createCacheService");var y=r(e=>G(e)&&U(e,"Cache.Service"),"isCacheServiceDeclaration"),C=r(e=>{let i={},
+t=[];for(let c in e){let n=e[c];if(!y(n)||B(n))continue;let o=T(n.name),s=new Set(
+["engine"]),d=n.file;n.description&&(o.description=n.description);for(let a of Q(
+n))if(X(a))switch(a.name){default:{t.push(new V(o.name,a.name,d));break}case"cli\
+ent":break;case"engine":{(o.engine=h(a.value,n,e,t))&&s.delete(a.name);break}case"\
+variables":{o.variables=K(a,t);break}case"services":{o.services=J(a,e,t);break}}
+if(!Z(o)){t.push(new p([...s],d));continue}if(i[n.name]){t.push(new N(n.name,d));
+continue}i[n.name]=o}return{services:i,errors:t}},"getCacheServicesMetadata"),Z=r(
+e=>Y(e,["engine","variables","services"]),"isCompleteService");var S=r(e=>y(e)?e.name:null,"getLinkedService");var Oe=r(()=>{_(),$(g,{"metadata:getServices":C,"metadata:getLinkedService":S})},
+"registerTriggers");export{m as IncompleteEngineError,p as IncompleteServiceError,f as IncorrectEngineTypeError,
+l as InvalidEngineTypeError,g as ServiceType,T as createCacheService,h as getCacheEngineMetadata,
+C as getCacheServicesMetadata,S as getLinkedService,W as isCacheEngineDeclaration,
+de as isCacheService,y as isCacheServiceDeclaration,Oe as registerTriggers};
+//# sourceMappingURL=library.mjs.map

package/dist/main.cjs

@@ -0,0 +1,4 @@
+"use strict";var o=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var l=(n,e)=>{for(var t in e)o(n,t,{get:e[t],enumerable:!0})},s=(n,e,t,i)=>{if(e&&
+typeof e=="object"||typeof e=="function")for(let r of c(e))!a.call(n,r)&&r!==t&&
+o(n,r,{get:()=>e[r],enumerable:!(i=p(e,r))||i.enumerable});return n};var g=n=>s(o({},"__esModule",{value:!0}),n);var x={};l(x,{Cache:()=>m});module.exports=g(x);var m;(n=>{})(m||={});0&&(module.exports={Cache});
+//# sourceMappingURL=main.cjs.map

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export * from './services/contract';
+export * from './services/client';

package/dist/main.mjs

@@ -0,0 +1,2 @@
+var e;(n=>{})(e||={});export{e as Cache};
+//# sourceMappingURL=main.mjs.map

package/dist/metadata/engine.d.ts

@@ -0,0 +1,4 @@
+import type { AllType, ReflectionTypes, TypeModel } from '@ez4/reflection';
+import type { CacheEngine } from './types';
+export declare const isCacheEngineDeclaration: (type: TypeModel) => boolean;
+export declare const getCacheEngineMetadata: (type: AllType, parent: TypeModel, reflection: ReflectionTypes, errorList: Error[]) => CacheEngine | undefined;

package/dist/metadata/service.d.ts

@@ -0,0 +1,7 @@
+import type { AllType, ReflectionTypes, TypeClass } from '@ez4/reflection';
+import type { CacheService } from './types';
+export declare const isCacheServiceDeclaration: (type: AllType) => type is TypeClass;
+export declare const getCacheServicesMetadata: (reflection: ReflectionTypes) => {
+    services: Record<string, CacheService>;
+    errors: Error[];
+};

package/dist/metadata/types.d.ts

@@ -0,0 +1,20 @@
+import type { ServiceMetadata } from '@ez4/project/library';
+export declare const ServiceType = "@ez4/cache";
+export type CacheService = Omit<ServiceMetadata, 'variables' | 'services'> & Required<Pick<ServiceMetadata, 'variables' | 'services'>> & {
+    type: typeof ServiceType;
+    description?: string;
+    engine: CacheEngine;
+};
+export type CacheEngine = {
+    name: string;
+};
+export declare const isCacheService: (service: ServiceMetadata) => service is CacheService;
+export declare const createCacheService: (name: string) => {
+    variables: {};
+    services: {};
+    type: "@ez4/cache";
+    name: string;
+    context: Record<string, import("@ez4/project/library").LinkedContext>;
+    description?: string | null | undefined;
+    engine?: CacheEngine | null | undefined;
+};

package/dist/services/client.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cache client.
+ */
+export interface Client {
+    /**
+     * Clear the entire cache removing all its keys.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the value corresponding to the given key.
+     *
+     * @param key Key name.
+     * @return Returns the corresponding key value or `undefined`.
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * Set the given value into the given key.
+     *
+     * @param key Key name.
+     * @param value Key value.
+     * @param options Options when setting the key.
+     */
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    /**
+     * Set the expiration TTL for the given key.
+     *
+     * @param key Key name.
+     * @param ttl TTL for the key (in seconds).
+     * @returns Returns the `true` when the TTL is applied, `false` otherwise.
+     */
+    setTTL(key: string, ttl: number): Promise<boolean>;
+    /**
+     * Get the current TTL for the given key.
+     *
+     * @param key Key name.
+     * @returns Returns the current TTL or `undefined` when there's none.
+     */
+    getTTL(key: string): Promise<number | undefined>;
+    /**
+     * Rename the given key.
+     *
+     * @param key Key name.
+     * @param newkey New key name.
+     * @returns Returns `true` when the key is renamed, `false` otherwise.
+     */
+    rename(key: string, newkey: string): Promise<boolean>;
+    /**
+     * Delete all the given keys.
+     *
+     * @param keys Key names.
+     * @returns Returns the number of deleted keys.
+     */
+    delete(...keys: string[]): Promise<number>;
+    /**
+     * Determines whether the given keys exists.
+     *
+     * @param keys Key names.
+     * @returns Returns the number of existing keys.
+     */
+    exists(...keys: string[]): Promise<number>;
+    /**
+     * Increment the current value for the given key.
+     *
+     * @param key Key name.
+     * @param value Optional increment value. (Default is `1`)
+     * @returns Returns the final value.
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement the current value for the given key.
+     *
+     * @param key Key name.
+     * @param value Optional decrement value. (Default is `1`)
+     * @returns Returns the final value.
+     */
+    decrement(key: string, value?: number): Promise<number>;
+}
+/**
+ * Options for setting keys.
+ */
+export type SetOptions = {
+    /**
+     * TTL for the key.
+     */
+    ttl?: number;
+};

package/dist/services/contract.d.ts

@@ -0,0 +1,27 @@
+import type { Service as CommonService } from '@ez4/common';
+import type { CacheEngine } from './engine';
+import type { Client } from './client';
+/**
+ * Provide all contracts for a self-managed cache service.
+ */
+export declare namespace Cache {
+    type Engine = CacheEngine;
+    /**
+     * Cache Engine definition.
+     */
+    type UseEngine<T extends CacheEngine> = T;
+    /**
+     * Cache service.
+     */
+    abstract class Service implements CommonService.Provider {
+        /**
+         * Determines which cache engine to use.
+         * Check the provider package to know all the possible values.
+         */
+        abstract readonly engine: Engine;
+        /**
+         * Service client.
+         */
+        readonly client: Client;
+    }
+}

package/dist/services/engine.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Cache engine.
+ */
+export type CacheEngine = {
+    name: string;
+};

package/dist/triggers/register.d.ts

@@ -0,0 +1 @@
+export declare const registerTriggers: () => void;

package/dist/triggers/service.d.ts

@@ -0,0 +1,2 @@
+import type { TypeClass } from '@ez4/reflection';
+export declare const getLinkedService: (declaration: TypeClass) => string | null;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ez4/cache",
+  "description": "EZ4: Components to build cache services",
+  "version": "0.42.0",
+  "author": "Silas B.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "ez4"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sbalmt/ez4.git",
+    "directory": "contracts/cache"
+  },
+  "engines": {
+    "node": ">=22.7"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "require": "./dist/main.cjs",
+      "import": "./dist/main.mjs"
+    },
+    "./library": {
+      "types": "./dist/library.d.ts",
+      "require": "./dist/library.cjs",
+      "import": "./dist/library.mjs"
+    }
+  },
+  "sideEffects": [
+    "./dist/library.cjs",
+    "./dist/library.mjs"
+  ],
+  "workspaces": [
+    "foundation/*",
+    "contracts/*"
+  ],
+  "scripts": {
+    "lint": "eslint --cache",
+    "clean": "rm -rf dist/* *.tsbuildinfo .eslintcache",
+    "build": "tsc && node tools/bundler.mjs",
+    "test": "npm run build && tsc -p tsconfig.test.json && ez4 test",
+    "local:publish": "npm run build && npm run clean:registry && npm publish --registry http://localhost:4873",
+    "clean:registry": "rm -rf ../../.registry/@ez4/cache",
+    "live:publish": "npm run build && npm publish --access public"
+  },
+  "dependencies": {
+    "@ez4/common": "^0.42.0",
+    "@ez4/project": "^0.42.0",
+    "@ez4/reflection": "^0.42.0",
+    "@ez4/utils": "^0.42.0"
+  }
+}