@daiso-tech/core 0.45.0 → 0.47.0

package/README.md

@@ -1,64 +1,70 @@
+# @daiso-tech/core
+
 [![npm version](https://img.shields.io/npm/v/@daiso-tech/core)](https://www.npmjs.com/package/@daiso-tech/core)
 ![NPM Downloads](https://img.shields.io/npm/dy/@daiso-tech/core)
-![Static Badge](https://img.shields.io/badge/TypeScript-3178C6?logo=TypeScript&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=TypeScript&logoColor=white)
 [![ES Modules](https://img.shields.io/badge/module%20type-ESM-blue)](https://nodejs.org/api/esm.html)
 [![License](https://img.shields.io/npm/l/@daiso-tech/core)](LICENSE)
 
-# @daiso-tech/core
-
-`@daiso-tech/core` is a TypeScript-first backend library for building web apps and API servers. It includes an ecosystem of official packages designed to work seamlessly together.
-
-**@daiso-tech/core** is a library of backend server components designed for maximum flexibility. While each component is fully functional on its own, they are written to work seamlessly together to build robust server-side logic.
-
-Key Features:
-- **Framework Agnostic:** Built without a dependency injection (DI) container, the library integrates effortlessly into any framework / library. Whether you use Express.js, backend frameworks like AdonisJS or NestJS, or full-stack frameworks like Next.js, Nuxt, or TanStack Start, these components "just work."
-
-- **Runtime Portability:** By leveraging the Adapter Pattern, the library remains decoupled from specific runtimes. Easily implement custom adapters, such as Cloudflare Durable Objects or Amazon DynamoDB, for better serverless integration with cloudflare workers or aws lambda.
-
-- **Test Friendly:** Testing is simple because every component comes with an "in-memory" adapter. This means you can run your tests instantly without needing to connect to a real database or server.
-
-- **Developer Friendly:** Save time with high-quality documentation and a readable, well-documented codebase. Clear comments and a logical structure make it easy to understand and extend system functionality.
-
-- **Type safe:**
-  We pay a closer look at type-safety, seamless intellisense, and support for auto imports when designing library APIs.
+`@daiso-tech/core` is a **TypeScript-first backend toolkit** designed for building resilient web applications and API servers. It provides a suite of decoupled, high-performance components that work seamlessly across any JavaScript runtime.
 
-- **ESM ready:**
-  @daiso-tech/core leverages modern JavaScript primitives, including ES modules
+[**Explore the Docs**](https://daiso-core.vercel.app/docs/Installation) | [**NPM Package**](https://www.npmjs.com/package/@daiso-tech/core)
 
-- **Supports standard schema:**
-  Integrated seamlessly with [standard schema](https://standardschema.dev/) allowing you to use libraries like zod to ensure both compile time and runtime typesafety.
+---
 
-[Get started now](https://daiso-core.vercel.app/docs/Installation)
+## 🚀 Key Features
 
-## A growing collection of officially maintained components
+* **Framework Agnostic** No Dependency Injection (DI) containers required. Effortlessly integrate with Express, NestJS, AdonisJS, or full-stack frameworks like Next.js, Nuxt, and TanStack Start.
+* **Runtime Portability** Leverages the **Adapter Pattern** to decouple your logic from the runtime. Switch between Node.js, Cloudflare Workers (Durable Objects), or AWS Lambda without rewriting core logic.
+* **Test-Driven Excellence** Every component includes a built-in **"in-memory" adapter**. Run unit tests instantly without spinning up databases or external infrastructure.
+* **Type Safety & DX** Deep IntelliSense support and strict type-safety. Designed for auto-imports and modern developer workflows.
+* **Standard Schema Support** Native integration with [Standard Schema](https://standardschema.dev/), allowing you to use **Zod**, **Valibot**, or **ArkType** for unified runtime validation.
 
-- **Cache:**
-  Speed up your applications by storing slowly changing data in a cache store.
+---
 
-- **EventBus:**
-  Easily send events accross different applications or in-memory.
+## 🛠 Quick Start
 
-- **Circuit-breaker:**
-  A circuit-breaker is a resilience primitive preventing cascading failures from external services by stopping calls to a failing service.
+```bash
+npm install @daiso-tech/core
+```
 
-- **Rate-limiter:**
-  A Rate-limiter is a resilience primitive used to control the rate of traffic sent or received by a network interface or a service.
+## 📦 Core Components
 
-- **Lock:**
-  Synchronize the access to a shared resource to prevents several processes, or concurrent code, from executing a section of code at the same time.
+The `@daiso-tech/core` ecosystem provides a growing collection of officially maintained primitives for building robust systems:
 
-- **Semaphore:**
-  A semaphore is a concurrency control primitive used to limit the number of processes or systems that can access a shared resource of code concurrently.
+### Resilience
+| | |
+| :--- | :--- |
+| **Circuit Breaker** | Prevents cascading failures by stopping calls to failing external services. |
+| **Rate Limiter** | Controls traffic flow to protect your network interfaces and services. |
+| **Retry** | Retry middleware with support for different backoffs with jitter. |
+| **Timeout** | Timeout middleware that prevents resource exhaustion by killing long-running tasks. |
+| **Fallback** | Fallback middleware that ensures graceful degradation by returning default values. |
 
-- **Shared-lock:**
-  A shared-lock (a.k.a reader writer lock) is a concurrency primitive offering better concurrency than a lock by coordinating a reader semaphore for concurrent access and an writer lock for mutual exclusion, strictly preventing conflicting simultaneous access and maintaining data consistency.
+### Concurrency
+| | |
+| :--- | :--- |
+| **Lock** | Ensures mutual exclusion for shared resources across servers or procceses. |
+| **Semaphore** | Limits the number of concurrent servers or procceses accessing a specific resource. |
+| **Shared Lock** | Reader-writer lock coordinating concurrent reads and exclusive writes. |
 
-- **Serde:**
-  Add custom serialization and deserialization logic that seamlessly integrates with all other components.
+### Misc
+| | |
+| :--- | :--- |
+| **Cache** | High-performance caching with support for multiple store adapters. |
+| **EventBus** | Decoupled event-driven communication (In-memory or Distributed via redis). |
 
-- **Collection:**
-  Effortlessly work with Arrays, Iterables, and AsyncIterables. Filter and transform with precision.
+### Utilities
+| | |
+| :--- | :--- |
+| **Hooks** | Agnostic sync/async middleware that integrates with all components. |
+| **Serde** | Custom serialization/deserialization logic that integrates with all components. |
+| **Collection** | Precision filtering and transformation for Arrays, Iterables, AsyncIterables and ArrayLike objects. |
+| **TimeSpan** | A duration class offering seamless time manipulation while integrating with all components. |
+---
 
-- **Hooks:**
-  Extend any sync and async function with agnostic hooks.@daiso-tech/core includes predefined retry, fallback, timeout and hedging hooks to easily allow handling transient failures.
+## 🛠 Quick Start
 
+```bash
+npm install @daiso-tech/core
+```

package/dist/cache/contracts/cache-adapter.contract.d.ts

@@ -42,7 +42,7 @@ export type ICacheAdapter<TType = unknown> = {
     /**
      * The `removeMany` method removes many keys. Returns true if one of the keys where deleted otherwise false is returned.
      */
-    removeMany(keys: string[]): Promise<boolean>;
+    removeMany(keys: Array<string>): Promise<boolean>;
     /**
      * The `removeAll` method removes all keys from the cache.
      */

package/dist/cache/contracts/cache.events.d.ts

@@ -85,7 +85,7 @@ export type ClearedCacheEvent = {};
  * @group Events
  */
 export type UnexpectedErrorCacheEvent = {
-    keys?: string[];
+    keys?: Array<string>;
     value?: unknown;
     method: string;
     error: unknown;

package/dist/cache/contracts/database-cache-adapter.contract.d.ts

@@ -1,6 +1,7 @@
 /**
  * @module Cache
  */
+import { type InvokableFn } from "../../utilities/_module.js";
 /**
  *
  * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
@@ -11,32 +12,20 @@ export type ICacheData<TType = unknown> = {
     expiration: Date | null;
 };
 /**
- *
  * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
  * @group Contracts
  */
-export type ICacheDataExpiration = {
-    expiration: Date | null;
+export type IDatabaseCacheTransaction<TType = unknown> = {
+    find(key: string): Promise<ICacheData<TType> | null>;
+    upsert(key: string, value: TType, expiration?: Date | null): Promise<void>;
 };
 /**
- *
  * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
  * @group Contracts
  */
-export type ICacheInsert<TType = unknown> = {
-    key: string;
-    value: TType;
+export type ICacheDataExpiration = {
     expiration: Date | null;
 };
-/**
- *
- * IMPORT_PATH: `"@daiso-tech/core/cache/contracts"`
- * @group Contracts
- */
-export type ICacheUpdate<TType = unknown> = {
-    key: string;
-    value: TType;
-};
 /**
  * The `IDatabaseCacheAdapter` contract defines a way for as key-value pairs independent of data storage.
  * This contract simplifies the implementation of cache adapters with CRUD-based databases, such as SQL databases and ORMs like TypeOrm and MikroOrm.
@@ -45,39 +34,12 @@ export type ICacheUpdate<TType = unknown> = {
  * @group Contracts
  */
 export type IDatabaseCacheAdapter<TType = unknown> = {
-    /**
-     * The `find` method returns the the `key` data which includs {@link ICacheData | `ICacheData.value`}  and {@link ICacheData | `ICacheData.expiration`}.
-     */
     find(key: string): Promise<ICacheData<TType> | null>;
-    /**
-     * The `insert` method inserts the given cache `data`.
-     */
-    insert(data: ICacheInsert<TType>): Promise<void>;
-    /**
-     * The `upsert` method inserts a key and if the key already exists then key will be updated with new `data.value` and `data.expiration`.
-     * The method always returns the old cache data if it exists otherwise null will be returned.
-     */
-    upsert(data: ICacheInsert<TType>): Promise<ICacheDataExpiration | null>;
-    /**
-     * The `removeExpiredMany` method updates a expired `key`.
-     */
-    updateExpired(data: ICacheInsert<TType>): Promise<number>;
-    /**
-     * The `removeExpiredMany` method updates a unexpired `key`.
-     */
-    updateUnexpired(data: ICacheUpdate<TType>): Promise<number>;
-    /**
-     * The `incrementUnexpired` should always throw an error if the existing item is not a number type.
-     */
-    incrementUnexpired(data: ICacheUpdate<number>): Promise<number>;
-    /**
-     * The `removeExpiredMany` method removes multiple expired `keys`.
-     */
-    removeExpiredMany(keys: string[]): Promise<number>;
-    /**
-     * The `removeExpiredMany` method removes multiple unexpired `keys`.
-     */
-    removeUnexpiredMany(keys: string[]): Promise<number>;
+    transaction<TValue>(trxFn: InvokableFn<[
+        trx: IDatabaseCacheTransaction<TType>
+    ], Promise<TValue>>): Promise<TValue>;
+    update(key: string, value: TType): Promise<ICacheDataExpiration | null>;
+    removeMany(keys: Array<string>): Promise<Array<ICacheDataExpiration>>;
     /**
      * The `removeAll` method removes all keys from the cache.
      */

package/dist/cache/contracts/database-cache-adapter.contract.js

@@ -1,5 +1,5 @@
 /**
  * @module Cache
  */
-export {};
+import {} from "../../utilities/_module.js";
 //# sourceMappingURL=database-cache-adapter.contract.js.map

package/dist/cache/contracts/database-cache-adapter.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"database-cache-adapter.contract.js","sourceRoot":"","sources":["../../../src/cache/contracts/database-cache-adapter.contract.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"database-cache-adapter.contract.js","sourceRoot":"","sources":["../../../src/cache/contracts/database-cache-adapter.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,MAAM,wBAAwB,CAAC"}

package/dist/cache/implementations/adapters/kysely-cache-adapter/kysely-cache-adapter.d.ts

@@ -2,35 +2,32 @@
  * @module Cache
  */
 import { type Kysely } from "kysely";
-import { type ICacheData, type ICacheInsert, type ICacheUpdate, type IDatabaseCacheAdapter } from "../../../../cache/contracts/_module.js";
+import { type ICacheData, type ICacheDataExpiration, type IDatabaseCacheAdapter, type IDatabaseCacheTransaction } from "../../../../cache/contracts/_module.js";
 import { type ISerde } from "../../../../serde/contracts/_module.js";
 import { type ITimeSpan } from "../../../../time-span/contracts/_module.js";
-import { type IDeinitizable, type IInitizable, type IPrunable } from "../../../../utilities/_module.js";
+import { type IDeinitizable, type IInitizable, type InvokableFn, type IPrunable } from "../../../../utilities/_module.js";
 /**
- *
  * IMPORT_PATH: `"@daiso-tech/core/cache/kysely-cache-adapter"`
  * @group Adapters
  */
-export type KyselyCacheAdapterTable = {
+export type KyselyCacheTable = {
     key: string;
     value: string;
     expiration: number | string | null;
 };
 /**
- *
  * IMPORT_PATH: `"@daiso-tech/core/cache/kysely-cache-adapter"`
  * @group Adapters
  */
-export type KyselyCacheAdapterTables = {
-    cache: KyselyCacheAdapterTable;
+export type KyselyCacheTables = {
+    cache: KyselyCacheTable;
 };
 /**
- *
  * IMPORT_PATH: `"@daiso-tech/core/cache/kysely-cache-adapter"`
  * @group Adapters
  */
 export type KyselyCacheAdapterSettings = {
-    kysely: Kysely<KyselyCacheAdapterTables>;
+    kysely: Kysely<KyselyCacheTables>;
     serde: ISerde<string>;
     /**
      * @default
@@ -45,7 +42,27 @@ export type KyselyCacheAdapterSettings = {
      * @default true
      */
     shouldRemoveExpiredKeys?: boolean;
+    /**
+     * @default
+     * ```ts
+     * import { Transaction } from "kysely"
+     *
+     * !(settings.kysely instanceof Transaction)
+     * ```
+     */
+    enableTransactions?: boolean;
 };
+/**
+ * @internal
+ */
+export declare class DatabaseCacheTransaction<TType> implements IDatabaseCacheTransaction<TType> {
+    private readonly kysely;
+    private readonly serde;
+    private readonly isMysql;
+    constructor(kysely: Kysely<KyselyCacheTables>, serde: ISerde<string>);
+    find(key: string): Promise<ICacheData<TType> | null>;
+    upsert(key: string, value: TType, expiration?: Date | null): Promise<void>;
+}
 /**
  * To utilize the `KyselyCacheAdapter`, you must install the [`"kysely"`](https://www.npmjs.com/package/kysely) package and configure a `Kysely` class instance.
  * The adapter have been tested with `sqlite`, `postgres` and `mysql` databases.
@@ -54,14 +71,13 @@ export type KyselyCacheAdapterSettings = {
  * @group Adapters
  */
 export declare class KyselyCacheAdapter<TType = unknown> implements IDatabaseCacheAdapter<TType>, IInitizable, IDeinitizable, IPrunable {
-    private static filterUnexpiredKeys;
-    private static filterExpiredKeys;
+    private readonly isMysql;
     private readonly serde;
     private readonly kysely;
     private readonly shouldRemoveExpiredKeys;
     private readonly expiredKeysRemovalInterval;
     private timeoutId;
-    private readonly disableTransaction;
+    private readonly enableTransactions;
     /**
      * @example
      * ```ts
@@ -93,14 +109,12 @@ export declare class KyselyCacheAdapter<TType = unknown> implements IDatabaseCac
      */
     deInit(): Promise<void>;
     find(key: string): Promise<ICacheData<TType> | null>;
-    insert(data: ICacheInsert<TType>): Promise<void>;
-    private transaction;
-    upsert(data: ICacheInsert<TType>): Promise<ICacheData<TType> | null>;
-    updateExpired(data: ICacheInsert<TType>): Promise<number>;
-    updateUnexpired(data: ICacheUpdate<TType>): Promise<number>;
-    incrementUnexpired(data: ICacheUpdate<number>): Promise<number>;
-    removeExpiredMany(keys: string[]): Promise<number>;
-    removeUnexpiredMany(keys: string[]): Promise<number>;
+    private _transaction;
+    transaction<TValue>(trxFn: InvokableFn<[
+        trx: IDatabaseCacheTransaction<TType>
+    ], Promise<TValue>>): Promise<TValue>;
+    update(key: string, value: TType): Promise<ICacheDataExpiration | null>;
+    removeMany(keys: Array<string>): Promise<Array<ICacheDataExpiration>>;
     removeAll(): Promise<void>;
     removeByKeyPrefix(prefix: string): Promise<void>;
 }