@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/namespaces/types.d.cts

@@ -52,6 +52,10 @@ export declare enum StorageBindingKind {
     Shared = "shared",
     Dedicated = "dedicated"
 }
+export declare enum CredentialProvider {
+    Model = "model",
+    Filesystem = "filesystem"
+}
 export declare const IsolationTierOptions: IsolationTier[];
 export declare const MembershipStatusOptions: MembershipStatus[];
 export declare const PrincipalKindOptions: PrincipalKind[];
@@ -60,6 +64,7 @@ export declare const PermissionCategoryOptions: PermissionCategory[];
 export declare const ResourceVisibilityOptions: ResourceVisibility[];
 export declare const StorageKindOptions: StorageKind[];
 export declare const StorageBindingKindOptions: StorageBindingKind[];
+export declare const CredentialProviderOptions: CredentialProvider[];
 export type TxArgs = any[];
 export interface CreateTenantInput {
     slug: string;
@@ -162,6 +167,38 @@ export interface CreateStorageBindingInput {
     region: string;
     config?: Record<string, unknown>;
 }
+export interface CreateCredentialInput {
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface RotateCredentialInput {
+    credentialId: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    version?: string;
+}
+export interface CredentialSummary {
+    id: string;
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
 export interface BootstrapPermission {
     key: string;
     category: PermissionCategory;

package/lib/types/namespaces/types.d.mts

@@ -52,6 +52,10 @@ export declare enum StorageBindingKind {
     Shared = "shared",
     Dedicated = "dedicated"
 }
+export declare enum CredentialProvider {
+    Model = "model",
+    Filesystem = "filesystem"
+}
 export declare const IsolationTierOptions: IsolationTier[];
 export declare const MembershipStatusOptions: MembershipStatus[];
 export declare const PrincipalKindOptions: PrincipalKind[];
@@ -60,6 +64,7 @@ export declare const PermissionCategoryOptions: PermissionCategory[];
 export declare const ResourceVisibilityOptions: ResourceVisibility[];
 export declare const StorageKindOptions: StorageKind[];
 export declare const StorageBindingKindOptions: StorageBindingKind[];
+export declare const CredentialProviderOptions: CredentialProvider[];
 export type TxArgs = any[];
 export interface CreateTenantInput {
     slug: string;
@@ -162,6 +167,38 @@ export interface CreateStorageBindingInput {
     region: string;
     config?: Record<string, unknown>;
 }
+export interface CreateCredentialInput {
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+}
+export interface RotateCredentialInput {
+    credentialId: string;
+    secret: string | Record<string, unknown> | Uint8Array;
+    version?: string;
+}
+export interface CredentialSummary {
+    id: string;
+    tenantId: string;
+    orgUnitId?: string;
+    ownerPrincipalId?: string;
+    name: string;
+    credentialType: string;
+    provider: CredentialProvider;
+    description?: string;
+    enabled: boolean;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    lastUsedAt?: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
 export interface BootstrapPermission {
     key: string;
     category: PermissionCategory;

package/lib/types/redis/RedisContextLock.d.cts

@@ -0,0 +1,106 @@
+import { Context, ContextLock } from "@decaf-ts/core";
+import type { RedisAdapter } from "./adapter.d.cts";
+/**
+ * @description A pending write buffered for the duration of a transaction
+ * @summary `null` represents a pending delete; a string represents the serialized
+ * record to be written.
+ * @typedef {string | null} RedisBufferedValue
+ * @memberOf module:redis
+ */
+export type RedisBufferedValue = string | null;
+/**
+ * @description Redis-native transaction lock for the Redis adapter
+ * @summary Backs `@transactional()` with a dedicated Redis connection carrying a
+ * native `MULTI` command queue plus an in-memory read cache. Every CRUD write
+ * performed under an active transaction is queued on the native `MULTI` object and
+ * mirrored into the read cache, so the transaction observes its own writes
+ * (read-your-writes) while remaining invisible to every other connection until
+ * {@link RedisContextLock.commit} issues `WATCH` and `EXEC`. If a watched table
+ * changed concurrently, `EXEC` aborts and the transaction raises a
+ * `ConflictError` instead of silently overwriting the concurrent write.
+ *
+ * A dedicated connection is required: `WATCH` is per-connection state on the
+ * node-redis client, so a `WATCH` issued on the shared, multiplexed adapter
+ * client would be cleared or replaced by any concurrent adapter operation (and a
+ * concurrent write to a watched key would abort an unrelated transaction).
+ * @class RedisContextLock
+ * @category Redis
+ */
+export declare class RedisContextLock<A extends RedisAdapter = RedisAdapter> extends ContextLock<A> {
+    private txClient?;
+    private multi?;
+    private readCache;
+    /**
+     * @description Whether a Redis transaction is currently open
+     * @return {boolean} True while a transaction is active
+     */
+    get active(): boolean;
+    /**
+     * @description Returns the buffered entry for a record, when present
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @return {{found: boolean, value?: RedisBufferedValue}} The buffered entry state
+     */
+    getRecord(table: string, id: string): {
+        found: true;
+        value: RedisBufferedValue;
+    } | {
+        found: false;
+    };
+    /**
+     * @description Queues a serialized record on the native transaction and buffers it for reads
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @param {string} value - The serialized record
+     * @return {void}
+     */
+    setRecord(table: string, id: string, value: RedisBufferedValue): void;
+    /**
+     * @description Queues a record deletion on the native transaction and buffers it
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @return {void}
+     */
+    deleteRecord(table: string, id: string): void;
+    /**
+     * @description Returns the buffered writes for a table, when any exist
+     * @param {string} table - The table (model) name
+     * @return {Map<string, RedisBufferedValue> | undefined} The buffered entries
+     */
+    tableEntries(table: string): Map<string, RedisBufferedValue> | undefined;
+    /**
+     * @description Starts the transaction, opening a dedicated connection and native queue
+     * @summary Delegates to the base implementation so `maxConcurrentTransactions`
+     * continues to gate concurrency, then opens a dedicated connection and its native
+     * `MULTI` command queue.
+     * @param {Context<any>} context - The context the transaction is starting under
+     * @return {Promise<void>} A promise that resolves once the transaction is open
+     */
+    begin(context: Context<any>): Promise<void>;
+    /**
+     * @description Flushes the queued writes atomically and ends the transaction
+     * @summary `WATCH`es every touched table on the dedicated connection, then runs
+     * the native `MULTI` queue with `EXEC`. If a watched table changed concurrently,
+     * `EXEC` aborts with a `WatchError` and the transaction raises a
+     * `ConflictError`. On success (or conflict) the dedicated connection is released
+     * and the concurrency permit returned.
+     * @param {Context<any>} context - The context the transaction ran under
+     * @return {Promise<void>} A promise that resolves once the transaction ends
+     */
+    commit(context: Context<any>): Promise<void>;
+    /**
+     * @description Discards the queued writes and ends the transaction
+     * @param {Error} err - The error that triggered the rollback
+     * @param {Context<any>} context - The context the transaction ran under
+     * @return {Promise<void>} A promise that resolves once the transaction ends
+     */
+    rollback(err: Error, context: Context<any>): Promise<void>;
+    /**
+     * @description Releases the dedicated transaction connection and clears state
+     * @summary Unwatches and closes the dedicated connection, then clears the native
+     * queue and read cache so queued writes are never applied after rollback or after
+     * an already flushed commit.
+     * @return {Promise<void>} A promise that resolves once the connection is released
+     */
+    private releaseTx;
+}

package/lib/types/redis/RedisContextLock.d.mts

@@ -0,0 +1,106 @@
+import { Context, ContextLock } from "@decaf-ts/core";
+import type { RedisAdapter } from "./adapter.d.mts";
+/**
+ * @description A pending write buffered for the duration of a transaction
+ * @summary `null` represents a pending delete; a string represents the serialized
+ * record to be written.
+ * @typedef {string | null} RedisBufferedValue
+ * @memberOf module:redis
+ */
+export type RedisBufferedValue = string | null;
+/**
+ * @description Redis-native transaction lock for the Redis adapter
+ * @summary Backs `@transactional()` with a dedicated Redis connection carrying a
+ * native `MULTI` command queue plus an in-memory read cache. Every CRUD write
+ * performed under an active transaction is queued on the native `MULTI` object and
+ * mirrored into the read cache, so the transaction observes its own writes
+ * (read-your-writes) while remaining invisible to every other connection until
+ * {@link RedisContextLock.commit} issues `WATCH` and `EXEC`. If a watched table
+ * changed concurrently, `EXEC` aborts and the transaction raises a
+ * `ConflictError` instead of silently overwriting the concurrent write.
+ *
+ * A dedicated connection is required: `WATCH` is per-connection state on the
+ * node-redis client, so a `WATCH` issued on the shared, multiplexed adapter
+ * client would be cleared or replaced by any concurrent adapter operation (and a
+ * concurrent write to a watched key would abort an unrelated transaction).
+ * @class RedisContextLock
+ * @category Redis
+ */
+export declare class RedisContextLock<A extends RedisAdapter = RedisAdapter> extends ContextLock<A> {
+    private txClient?;
+    private multi?;
+    private readCache;
+    /**
+     * @description Whether a Redis transaction is currently open
+     * @return {boolean} True while a transaction is active
+     */
+    get active(): boolean;
+    /**
+     * @description Returns the buffered entry for a record, when present
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @return {{found: boolean, value?: RedisBufferedValue}} The buffered entry state
+     */
+    getRecord(table: string, id: string): {
+        found: true;
+        value: RedisBufferedValue;
+    } | {
+        found: false;
+    };
+    /**
+     * @description Queues a serialized record on the native transaction and buffers it for reads
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @param {string} value - The serialized record
+     * @return {void}
+     */
+    setRecord(table: string, id: string, value: RedisBufferedValue): void;
+    /**
+     * @description Queues a record deletion on the native transaction and buffers it
+     * @param {string} table - The table (model) name
+     * @param {string} id - The record id
+     * @return {void}
+     */
+    deleteRecord(table: string, id: string): void;
+    /**
+     * @description Returns the buffered writes for a table, when any exist
+     * @param {string} table - The table (model) name
+     * @return {Map<string, RedisBufferedValue> | undefined} The buffered entries
+     */
+    tableEntries(table: string): Map<string, RedisBufferedValue> | undefined;
+    /**
+     * @description Starts the transaction, opening a dedicated connection and native queue
+     * @summary Delegates to the base implementation so `maxConcurrentTransactions`
+     * continues to gate concurrency, then opens a dedicated connection and its native
+     * `MULTI` command queue.
+     * @param {Context<any>} context - The context the transaction is starting under
+     * @return {Promise<void>} A promise that resolves once the transaction is open
+     */
+    begin(context: Context<any>): Promise<void>;
+    /**
+     * @description Flushes the queued writes atomically and ends the transaction
+     * @summary `WATCH`es every touched table on the dedicated connection, then runs
+     * the native `MULTI` queue with `EXEC`. If a watched table changed concurrently,
+     * `EXEC` aborts with a `WatchError` and the transaction raises a
+     * `ConflictError`. On success (or conflict) the dedicated connection is released
+     * and the concurrency permit returned.
+     * @param {Context<any>} context - The context the transaction ran under
+     * @return {Promise<void>} A promise that resolves once the transaction ends
+     */
+    commit(context: Context<any>): Promise<void>;
+    /**
+     * @description Discards the queued writes and ends the transaction
+     * @param {Error} err - The error that triggered the rollback
+     * @param {Context<any>} context - The context the transaction ran under
+     * @return {Promise<void>} A promise that resolves once the transaction ends
+     */
+    rollback(err: Error, context: Context<any>): Promise<void>;
+    /**
+     * @description Releases the dedicated transaction connection and clears state
+     * @summary Unwatches and closes the dedicated connection, then clears the native
+     * queue and read cache so queued writes are never applied after rollback or after
+     * an already flushed commit.
+     * @return {Promise<void>} A promise that resolves once the connection is released
+     */
+    private releaseTx;
+}

package/lib/types/redis/RedisDispatch.d.cts

@@ -0,0 +1,56 @@
+import { ContextualArgs, Dispatch } from "@decaf-ts/core";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import type { RedisAdapter } from "./adapter.d.cts";
+import type { RedisContext } from "./types.d.cts";
+/**
+ * @description Dispatcher for Redis change events
+ * @summary Extends the core `Dispatch` to broadcast record changes over Redis
+ * pub/sub so that every process sharing the same database refreshes its observers.
+ * Local observer updates are still performed synchronously through the base class;
+ * the published message carries an `origin` id so a process ignores the echo of its
+ * own events and never notifies its observers twice.
+ * @class RedisDispatch
+ * @category Redis
+ */
+export declare class RedisDispatch extends Dispatch<RedisAdapter> {
+    private subscriber?;
+    private readonly origin;
+    /**
+     * @description Whether the pub/sub subscription is currently active
+     */
+    active: boolean;
+    /**
+     * @description Initializes the dispatcher and opens the pub/sub subscription
+     * @summary Proxies the adapter's CRUD methods through the base implementation,
+     * then opens a dedicated subscriber connection listening for change events.
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once initialization is complete
+     */
+    protected initialize(...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Closes the dispatcher and releases the pub/sub subscription
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once the dispatcher is closed
+     */
+    close(...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Notifies local observers and broadcasts the event to other processes
+     * @summary Performs the base local refresh, then publishes the change to the
+     * Redis pub/sub channel. Remote processes receive the event and refresh their own
+     * observers; the originating process ignores its own message.
+     * @param {Constructor<any> | string} model - The model (or table name) that changed
+     * @param {OperationKeys | BulkCrudOperationKeys | string} event - The operation that occurred
+     * @param {any} id - The identifier(s) of the affected record(s)
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once observers are notified
+     */
+    updateObservers(model: any, event: OperationKeys | BulkCrudOperationKeys | string, id: any, ...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Handles an incoming Redis change event
+     * @summary Ignores the echo of locally published events and refreshes the
+     * observers of this process for events published elsewhere.
+     * @param {string} message - The raw JSON pub/sub payload
+     * @return {Promise<void>} A promise that resolves once observers are notified
+     */
+    protected changeHandler(message: string): Promise<void>;
+}

package/lib/types/redis/RedisDispatch.d.mts

@@ -0,0 +1,56 @@
+import { ContextualArgs, Dispatch } from "@decaf-ts/core";
+import { BulkCrudOperationKeys, OperationKeys } from "@decaf-ts/db-decorators";
+import type { RedisAdapter } from "./adapter.d.mts";
+import type { RedisContext } from "./types.d.mts";
+/**
+ * @description Dispatcher for Redis change events
+ * @summary Extends the core `Dispatch` to broadcast record changes over Redis
+ * pub/sub so that every process sharing the same database refreshes its observers.
+ * Local observer updates are still performed synchronously through the base class;
+ * the published message carries an `origin` id so a process ignores the echo of its
+ * own events and never notifies its observers twice.
+ * @class RedisDispatch
+ * @category Redis
+ */
+export declare class RedisDispatch extends Dispatch<RedisAdapter> {
+    private subscriber?;
+    private readonly origin;
+    /**
+     * @description Whether the pub/sub subscription is currently active
+     */
+    active: boolean;
+    /**
+     * @description Initializes the dispatcher and opens the pub/sub subscription
+     * @summary Proxies the adapter's CRUD methods through the base implementation,
+     * then opens a dedicated subscriber connection listening for change events.
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once initialization is complete
+     */
+    protected initialize(...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Closes the dispatcher and releases the pub/sub subscription
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once the dispatcher is closed
+     */
+    close(...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Notifies local observers and broadcasts the event to other processes
+     * @summary Performs the base local refresh, then publishes the change to the
+     * Redis pub/sub channel. Remote processes receive the event and refresh their own
+     * observers; the originating process ignores its own message.
+     * @param {Constructor<any> | string} model - The model (or table name) that changed
+     * @param {OperationKeys | BulkCrudOperationKeys | string} event - The operation that occurred
+     * @param {any} id - The identifier(s) of the affected record(s)
+     * @param {...ContextualArgs} args - Contextual arguments
+     * @return {Promise<void>} A promise that resolves once observers are notified
+     */
+    updateObservers(model: any, event: OperationKeys | BulkCrudOperationKeys | string, id: any, ...args: ContextualArgs<RedisContext>): Promise<void>;
+    /**
+     * @description Handles an incoming Redis change event
+     * @summary Ignores the echo of locally published events and refreshes the
+     * observers of this process for events published elsewhere.
+     * @param {string} message - The raw JSON pub/sub payload
+     * @return {Promise<void>} A promise that resolves once observers are notified
+     */
+    protected changeHandler(message: string): Promise<void>;
+}

package/lib/types/redis/RedisPaginator.d.cts

@@ -0,0 +1,58 @@
+import { RawRedisQuery } from "./types.d.cts";
+import { Adapter, MaybeContextualArg, Paginator } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import type { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Redis-specific paginator implementation
+ * @summary Extends the base Paginator class to provide pagination functionality for
+ * Redis adapter queries. This class handles the pagination of query results loaded
+ * from Redis, allowing for efficient retrieval of large result sets in smaller chunks.
+ * @template M - The model type being paginated
+ * @class RedisPaginator
+ * @category Redis
+ * @example
+ * ```typescript
+ * // Create a query for User model
+ * const query: RawRedisQuery<User> = {
+ *   select: undefined, // Select all fields
+ *   from: User,
+ *   where: (user) => user.active === true
+ * };
+ *
+ * // Create a paginator with page size of 10
+ * const paginator = new RedisPaginator<User>(adapter, query, 10, User);
+ *
+ * // Get the first page of results
+ * const firstPage = await paginator.page(1);
+ *
+ * // Get the next page
+ * const secondPage = await paginator.page(2);
+ * ```
+ */
+export declare class RedisPaginator<M extends Model> extends Paginator<M, M[], RawRedisQuery<M>> {
+    /**
+     * @description Creates a paginator bound to the Redis adapter
+     * @param {Adapter<any, any, RawRedisQuery<M>, any>} adapter - The Redis adapter instance
+     * @param {RawRedisQuery<M>} query - The raw query to paginate
+     * @param {number} size - The number of records per page
+     * @param {Constructor<M>} clazz - The model constructor being paginated
+     */
+    constructor(adapter: Adapter<any, any, RawRedisQuery<M>, any>, query: RawRedisQuery<M>, size: number, clazz: Constructor<M>);
+    /**
+     * @description Prepares a Redis query for pagination
+     * @summary Modifies the raw query statement to include pagination parameters.
+     * This protected method sets the limit parameter on the query to match the page size.
+     * @param {RawRedisQuery<M>} rawStatement - The original query statement
+     * @return {RawRedisQuery<M>} The modified query with pagination parameters
+     */
+    protected prepare(rawStatement: RawRedisQuery<M>): RawRedisQuery<M>;
+    /**
+     * @description Retrieves a specific page of results
+     * @summary Executes the query with pagination parameters to retrieve a specific page of results.
+     * This method calculates the appropriate skip value based on the page number and page size,
+     * executes the query, and updates the current page tracking.
+     * @param {number} [page=1] - The page number to retrieve (1-based)
+     * @return {Promise<R[]>} A promise that resolves to an array of results for the requested page
+     */
+    page(page?: number, ...args: MaybeContextualArg<any>): Promise<M[]>;
+}

package/lib/types/redis/RedisPaginator.d.mts

@@ -0,0 +1,58 @@
+import { RawRedisQuery } from "./types.d.mts";
+import { Adapter, MaybeContextualArg, Paginator } from "@decaf-ts/core";
+import { Model } from "@decaf-ts/decorator-validation";
+import type { Constructor } from "@decaf-ts/decoration";
+/**
+ * @description Redis-specific paginator implementation
+ * @summary Extends the base Paginator class to provide pagination functionality for
+ * Redis adapter queries. This class handles the pagination of query results loaded
+ * from Redis, allowing for efficient retrieval of large result sets in smaller chunks.
+ * @template M - The model type being paginated
+ * @class RedisPaginator
+ * @category Redis
+ * @example
+ * ```typescript
+ * // Create a query for User model
+ * const query: RawRedisQuery<User> = {
+ *   select: undefined, // Select all fields
+ *   from: User,
+ *   where: (user) => user.active === true
+ * };
+ *
+ * // Create a paginator with page size of 10
+ * const paginator = new RedisPaginator<User>(adapter, query, 10, User);
+ *
+ * // Get the first page of results
+ * const firstPage = await paginator.page(1);
+ *
+ * // Get the next page
+ * const secondPage = await paginator.page(2);
+ * ```
+ */
+export declare class RedisPaginator<M extends Model> extends Paginator<M, M[], RawRedisQuery<M>> {
+    /**
+     * @description Creates a paginator bound to the Redis adapter
+     * @param {Adapter<any, any, RawRedisQuery<M>, any>} adapter - The Redis adapter instance
+     * @param {RawRedisQuery<M>} query - The raw query to paginate
+     * @param {number} size - The number of records per page
+     * @param {Constructor<M>} clazz - The model constructor being paginated
+     */
+    constructor(adapter: Adapter<any, any, RawRedisQuery<M>, any>, query: RawRedisQuery<M>, size: number, clazz: Constructor<M>);
+    /**
+     * @description Prepares a Redis query for pagination
+     * @summary Modifies the raw query statement to include pagination parameters.
+     * This protected method sets the limit parameter on the query to match the page size.
+     * @param {RawRedisQuery<M>} rawStatement - The original query statement
+     * @return {RawRedisQuery<M>} The modified query with pagination parameters
+     */
+    protected prepare(rawStatement: RawRedisQuery<M>): RawRedisQuery<M>;
+    /**
+     * @description Retrieves a specific page of results
+     * @summary Executes the query with pagination parameters to retrieve a specific page of results.
+     * This method calculates the appropriate skip value based on the page number and page size,
+     * executes the query, and updates the current page tracking.
+     * @param {number} [page=1] - The page number to retrieve (1-based)
+     * @return {Promise<R[]>} A promise that resolves to an array of results for the requested page
+     */
+    page(page?: number, ...args: MaybeContextualArg<any>): Promise<M[]>;
+}