@tsed/directus-sdk 8.19.0

package/lib/types/fn/defineEndpoint.d.ts

@@ -0,0 +1,73 @@
+import type { EndpointConfig } from "@directus/types";
+/**
+ * Defines a Directus endpoint with Ts.ED dependency injection support.
+ *
+ * This function wraps the Directus SDK's `defineEndpoint` to automatically integrate
+ * Ts.ED's DI container, allowing you to use `inject()` to access services within
+ * your endpoint handlers. It also provides automatic error handling and logging.
+ *
+ * ### Basic endpoint with service injection
+ * ```ts
+ * import {defineEndpoint} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * export default defineEndpoint({
+ *   id: "my-custom-endpoint",
+ *   handler: (router) => {
+ *     router.get("/hello", async (req, res) => {
+ *       const myService = inject(MyService);
+ *       const result = await myService.doSomething();
+ *
+ *       return res.json(result);
+ *     });
+ *   }
+ * });
+ * ```
+ *
+ * ### Function-only configuration
+ *
+ * ```ts
+ * import {defineEndpoint} from "@tsed/directus-sdk";
+ *
+ * export default defineEndpoint((router, context) => {
+ *   router.post("/webhook", async (req, res) => {
+ *     const myService = inject(MyService);
+ *     const result = await myService.doSomething();
+ *     // Handle webhook
+ *     res.json({ success: true });
+ *   });
+ * });
+ * ```
+ *
+ * ### With multiple routes and error handling
+ *
+ * ```ts
+ * import {defineEndpoint} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * export default defineEndpoint({
+ *   id: "api-v1",
+ *   handler: (router) => {
+ *     router.get("/users", async (req, res) => {
+ *       const userService = inject(UserService);
+ *       const users = await userService.findAll();
+ *       res.json(users);
+ *     });
+ *
+ *     router.post("/auth/login", async (req, res) => {
+ *       const authService = inject(AuthService);
+ *       const token = await authService.authenticate(req.body);
+ *       res.json({ token });
+ *     });
+ *   }
+ * });
+ * ```
+ * @param config - The endpoint configuration. Can be either:
+ *   - A function that receives the router and context
+ *   - An object with `id` and `handler` properties
+ *
+ * @returns The configured endpoint ready to be exported from your extension file
+ * @see {@link wrapEndpoint} for the underlying wrapper implementation
+ * @see {@link https://docs.directus.io/extensions/endpoints.html} Directus Endpoints Documentation
+ */
+export declare function defineEndpoint(config: EndpointConfig): EndpointConfig;

package/lib/types/fn/defineHook.d.ts

@@ -0,0 +1,105 @@
+import "../bootstrap/runtime.js";
+import type { HookExtensionContext, RegisterFunctions } from "@directus/types";
+/**
+ * Defines a Directus hook with Ts.ED dependency injection support.
+ *
+ * This function wraps your hook callback to provide:
+ * - Automatic Ts.ED DI container initialization
+ * - Service injection via `inject()` function
+ * - Proper error handling and logging
+ * - Access to Directus context through `DirectusContextService`
+ *
+ * Hooks allow you to trigger custom logic when certain events occur in Directus,
+ * such as when items are created, updated, or deleted.
+ *
+ * ### Basic hook with filters
+ *
+ * ```ts
+ * import {defineHook} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * export default defineHook(({filter, action}) => {
+ *   const validationService = inject(ValidationService);
+ *
+ *   // Filter runs before the event (can modify data or cancel operation)
+ *   filter("items.create", async (payload, meta) => {
+ *     await validationService.validate(payload);
+ *     return payload;
+ *   });
+ *
+ *   // Action runs after the event (cannot modify data)
+ *   action("items.create", async (meta) => {
+ *     console.log("Item created:", meta.key);
+ *   });
+ * });
+ * ```
+ *
+ * ### Hook with service injection and multiple events
+ *
+ * ```ts
+ * import {defineHook} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ * import {logger} from "@tsed/logger";
+ *
+ * export default defineHook(({filter, action}) => {
+ *   const productService = inject(ProductService);
+ *   const notificationService = inject(NotificationService);
+ *
+ *   logger().info("Product hooks loaded");
+ *
+ *   // Ensure unique product rankings on create
+ *   filter("product_rankings.items.create", async (payload) => {
+ *     return productService.ensureUniqueRanking(payload);
+ *   });
+ *
+ *   // Ensure unique product rankings on update
+ *   filter("product_rankings.items.update", async (payload) => {
+ *     return productService.ensureUniqueRanking(payload);
+ *   });
+ *
+ *   // Send notification when product is published
+ *   action("products.items.update", async (meta, context) => {
+ *     if (context.payload.status === "published") {
+ *       await notificationService.sendPublishedNotification(meta.key);
+ *     }
+ *   });
+ *
+ *   // Return services for debugging/testing
+ *   return {
+ *     productService,
+ *     notificationService
+ *   };
+ * });
+ * ```
+ *
+ * ### Hook with init and schedule
+ *
+ * ```ts
+ * import {defineHook} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * export default defineHook(({init, schedule}) => {
+ *   const cacheService = inject(CacheService);
+ *   const syncService = inject(SyncService);
+ *
+ *   // Run once when Directus starts
+ *   init("app.before", async () => {
+ *     await cacheService.warmup();
+ *   });
+ *
+ *   // Run on a schedule (cron syntax)
+ *   schedule("0 * * * *", async () => {
+ *     await syncService.hourlySync();
+ *   });
+ * });
+ * ```
+ *
+ * @param callback - The hook initialization function that receives:
+ *   - `register` - Functions to register event handlers (filter, action, init, schedule, embed)
+ *   - `context` - The Directus hook extension context
+ *
+ * @returns A wrapped hook function ready to be exported from your extension file
+ * @see {@link DirectusContextService} to access Directus context within injected services
+ * @see {@link https://docs.directus.io/extensions/hooks.html} Directus Hooks Documentation
+ */
+export declare function defineHook(callback: (register: RegisterFunctions, context: HookExtensionContext) => unknown | Promise<unknown> | void): (register: RegisterFunctions, context: HookExtensionContext) => Promise<unknown>;

package/lib/types/fn/defineOperationApi.d.ts

@@ -0,0 +1,114 @@
+import { OperationApiConfig } from "@directus/types";
+/**
+ * Defines a Directus operation with Ts.ED dependency injection support.
+ *
+ * This function wraps the Directus SDK's `defineOperationApi` to automatically integrate
+ * Ts.ED's DI container, allowing you to use `inject()` to access services within your
+ * operation handlers. Operations are custom logic that can be used in Directus flows.
+ *
+ * ### Basic operation with service injection
+ *
+ * ```ts
+ * import {defineOperationApi} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * type SendEmailOptions = {
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * };
+ *
+ * export default defineOperationApi<SendEmailOptions>({
+ *   id: "send-email",
+ *   handler: async (options, context) => {
+ *     const emailService = inject(EmailService);
+ *
+ *     await emailService.send({
+ *       to: options.to,
+ *       subject: options.subject,
+ *       body: options.body
+ *     });
+ *
+ *     return {
+ *       success: true,
+ *       sentAt: new Date().toISOString()
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * ### Operation with external API call
+ *
+ * ```ts
+ * import {defineOperationApi} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * type WebhookOptions = {
+ *   url: string;
+ *   method: "GET" | "POST";
+ *   payload?: Record<string, any>;
+ * };
+ *
+ * export default defineOperationApi<WebhookOptions>({
+ *   id: "call-webhook",
+ *   handler: async (options, context) => {
+ *     const httpClient = inject(HttpClient);
+ *
+ *     const response = await httpClient.request({
+ *       url: options.url,
+ *       method: options.method,
+ *       data: options.payload
+ *     });
+ *
+ *     return {
+ *       statusCode: response.status,
+ *       data: response.data
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * ### Operation with database access
+ *
+ * ```ts
+ * import {defineOperationApi} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * type CalculateStatsOptions = {
+ *   collection: string;
+ *   field: string;
+ * };
+ *
+ * export default defineOperationApi<CalculateStatsOptions>({
+ *   id: "calculate-stats",
+ *   handler: async (options, context) => {
+ *     const statsService = inject(StatsService);
+ *     const directusContext = inject(DirectusContextService);
+ *
+ *     const itemsService = await directusContext.getItemsService(options.collection);
+ *     const items = await itemsService.readByQuery({ limit: -1 });
+ *
+ *     const stats = statsService.calculate(items, options.field);
+ *
+ *     return {
+ *       count: items.length,
+ *       average: stats.avg,
+ *       min: stats.min,
+ *       max: stats.max
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @template Options - Type definition for the operation's configuration options
+ *
+ * @param config - The operation configuration containing:
+ *   - `id` - Unique identifier for the operation
+ *   - `handler` - Function that executes the operation logic
+ *
+ * @returns The configured operation ready to be exported from your extension file
+ * @see {@link wrapOperation} for the underlying wrapper implementation
+ * @see {@link DirectusContextService} to access Directus context
+ * @see {@link https://docs.directus.io/extensions/operations.html} Directus Operations Documentation
+ */
+export declare function defineOperationApi<Options = Record<string, unknown>>(config: OperationApiConfig<Options>): OperationApiConfig<Options>;

package/lib/types/fn/wrapEndpoint.d.ts

@@ -0,0 +1,35 @@
+import "../bootstrap/runtime.js";
+import type { EndpointExtensionContext } from "@directus/types";
+import type { Router } from "express";
+/**
+ * Wraps an endpoint handler to provide Ts.ED dependency injection and error handling.
+ *
+ * This function is internally used by `defineEndpoint` to:
+ * - Initialize the Ts.ED DI container for each request
+ * - Wrap all Express router methods (GET, POST, PUT, DELETE, etc.)
+ * - Provide automatic error handling with proper HTTP responses
+ * - Attach Directus logger to the DI context
+ * - Log errors with structured error information
+ *
+ * Each route handler executes within its own DI context, allowing proper isolation
+ * and service injection via `inject()`.
+ *
+ * @param callback - The endpoint handler function that receives router and context
+ *
+ * @returns A wrapped handler that integrates with Directus and Ts.ED
+ *
+ * @remarks
+ * This is typically used internally by `defineEndpoint`. You generally don't need to
+ * call this directly unless you're building custom endpoint wrappers.
+ *
+ * Error handling:
+ * - Errors are caught and returned as JSON responses
+ * - Status code is extracted from `error.status` (defaults to 500)
+ * - Error message is extracted from `error.error_message` or `error.message`
+ * - Additional errors array is included if present in `error.errors`
+ * - All errors are logged with structured information (name, message, description, stack)
+ *
+ * @see {@link defineEndpoint} for the recommended way to create endpoints
+ * @see {@link DirectusContextService} to access Directus context in injected services
+ */
+export declare function wrapEndpoint(callback: (router: Router, context: EndpointExtensionContext) => void): (router: Router, context: EndpointExtensionContext) => void;

package/lib/types/fn/wrapOperation.d.ts

@@ -0,0 +1,35 @@
+import "../bootstrap/runtime.js";
+import type { OperationContext } from "@directus/types";
+/**
+ * Wraps an operation handler to provide Ts.ED dependency injection and error handling.
+ *
+ * This function is internally used by `defineOperationApi` to:
+ * - Initialize the Ts.ED DI container for each operation execution
+ * - Enable service injection via `inject()` within the operation handler
+ * - Provide automatic error handling and logging
+ * - Set up the Directus context in `DirectusContextService`
+ * - Create an isolated DI context for each operation run
+ *
+ * Each operation execution runs within its own DI context with platform set to
+ * `DIRECTUS_OPERATION`, ensuring proper isolation between different operation runs.
+ *
+ * @template Options - Type definition for the operation's configuration options
+ *
+ * @param callback - The operation handler function that receives options and context
+ *
+ * @returns A wrapped handler that integrates with Directus flows and Ts.ED
+ *
+ * @remarks
+ * This is typically used internally by `defineOperationApi`. You generally don't need
+ * to call this directly unless you're building custom operation wrappers.
+ *
+ * Error handling:
+ * - Errors are caught and logged with structured information
+ * - Error details include name, message, description, and stack trace
+ * - Logger is automatically flushed after error logging
+ * - The error is not re-thrown, allowing the flow to continue
+ *
+ * @see {@link defineOperationApi} for the recommended way to create operations
+ * @see {@link DirectusContextService} to access Directus context in injected services
+ */
+export declare function wrapOperation<Options = Record<string, unknown>>(callback: (options: Options, context: OperationContext) => unknown | Promise<unknown> | void): (options: Options, context: OperationContext) => Promise<unknown>;

package/lib/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./bootstrap/attach-logger.js";
+export * from "./bootstrap/runtime.js";
+export * from "./decorators/cache.js";
+export * from "./fn/defineEndpoint.js";
+export * from "./fn/defineHook.js";
+export * from "./fn/defineOperationApi.js";
+export * from "./fn/wrapEndpoint.js";
+export * from "./fn/wrapOperation.js";
+export * from "./services/DirectusCacheInterceptor.js";
+export * from "./services/DirectusContextService.js";
+export * from "./services/DirectusItemsRepository.js";

package/lib/types/services/DirectusCacheInterceptor.d.ts

@@ -0,0 +1,154 @@
+import type { Type } from "@tsed/core";
+import { type InterceptorContext, type InterceptorMethods } from "@tsed/di";
+/**
+ * Configuration options for the DirectusCacheInterceptor.
+ *
+ * @property ttl - Time to live in milliseconds for cached values (default: 900000ms = 15 minutes)
+ * @property keyGenerator - Custom function to generate cache keys from method arguments
+ * @property namespace - Custom namespace for cache keys (default: className:methodName)
+ * @property useSystemCache - Whether to use Directus system cache (true) or regular cache (false). Default: true
+ */
+export type DirectusCacheOptions = {
+    ttl?: number;
+    keyGenerator?: (...args: unknown[]) => string;
+    namespace?: string;
+    useSystemCache?: boolean;
+};
+/**
+ * Interceptor that provides caching functionality using Directus cache infrastructure.
+ *
+ * This interceptor wraps method calls to cache their results based on method arguments.
+ * It integrates with Directus's built-in caching system and supports both system cache
+ * and regular cache.
+ *
+ * Features:
+ * - Automatic cache key generation based on class name, method name, and arguments
+ * - Configurable TTL (time to live) for cached values
+ * - Custom key generators for complex caching strategies
+ * - Support for both system cache and regular cache
+ * - Proper handling of falsy values (null, false, 0, empty string)
+ *
+ * ### Direct usage with bindIntercept
+ *
+ * ```ts
+ * import {DirectusCacheInterceptor, useDirectusCache} from "@tsed/directus-sdk";
+ * import {injectable} from "@tsed/di";
+ *
+ * export class MyService {
+ *   search(query: string) {
+ *     // Expensive operation
+ *     return this.performSearch(query);
+ *   }
+ * }
+ *
+ * // Apply cache programmatically
+ * injectable(MyService);
+ * useDirectusCache(MyService, "search", { ttl: 60000 });
+ * ```
+ * @remarks
+ * This interceptor is typically used via the `@Cache` decorator rather than directly.
+ * The cache key format is: `{namespace}:{keyGenerator(...args)}`
+ * where namespace defaults to `snake_case_class_name:methodName`
+ *
+ * @see {@link Cache} decorator for the recommended usage
+ * @see {@link useDirectusCache} for programmatic cache binding
+ */
+export declare class DirectusCacheInterceptor implements InterceptorMethods {
+    /**
+     * Intercepts a method call to provide caching functionality.
+     *
+     * The interception flow:
+     * 1. Extract cache options from the context
+     * 2. Generate a cache key based on class name, method name, and arguments
+     * 3. Check if a cached value exists
+     * 4. If cached, return the cached value (skipping method execution)
+     * 5. If not cached, execute the method
+     * 6. Store the result in cache with the specified TTL
+     * 7. Return the result
+     *
+     * ### Cache key generation
+     *
+     * ```ts
+     * // For class MyService with method search("query")
+     * // Default namespace: "my_service:search"
+     * // Full cache key: "my_service:search:["query"]"
+     * ```
+     * @param context - The interceptor context containing method information and options
+     *
+     * @returns The cached or newly computed result of the method call
+     *
+     * @remarks
+     * - The cache check uses strict inequality (`!== undefined`) to allow caching falsy values
+     * - Cache keys are automatically namespaced to avoid collisions between different methods
+     * - The system cache is used by default, which persists across requests
+     */
+    intercept(context: InterceptorContext<unknown, DirectusCacheOptions>): Promise<any>;
+}
+/**
+ * Programmatically applies cache interception to a method using Directus cache infrastructure.
+ *
+ * This function allows you to add caching to a method after the class is defined,
+ * which is useful when you can't use decorators or need dynamic cache configuration.
+ *
+ * @example Basic usage
+ *
+ * ```ts
+ * import {injectable} from "@tsed/di";
+ * import {useDirectusCache} from "@tsed/directus-sdk";
+ *
+ * export class JiraIssueClient {
+ *   search(query: string) {
+ *     // Expensive search operation
+ *     return this.performSearch(query);
+ *   }
+ * }
+ *
+ * injectable(JiraIssueClient)
+ *
+ * // Apply cache after class definition
+ * useDirectusCache(JiraIssueClient, "search", { ttl: 900000 });
+ * ```
+ *
+ * ### With custom options
+ * ```ts
+ *
+ * useDirectusCache(MyService, "fetchData", {
+ *   ttl: 60000,
+ *   keyGenerator: (id: string) => `data:${id}`,
+ *   namespace: "my_service:data",
+ *   useSystemCache: false
+ * });
+ * ```
+ *
+ * ### Applying cache to multiple methods
+ *
+ * ```ts
+ * import {injectable} from "@tsed/di";
+ * import {useDirectusCache} from "@tsed/directus-sdk";
+ *
+ * export class ApiClient {
+ *   getUser(id: string) { }
+ *   getPosts() { }
+ * }
+ * injectable(ApiClient);
+ *
+ * useDirectusCache(ApiClient, "getUser", { ttl: 300000 });
+ * useDirectusCache(ApiClient, "getPosts", { ttl: 60000 });
+ * ```
+ *
+ * @template K - The class type
+ * @template Props - The property key type (method name)
+ *
+ * @param token - The class constructor to apply caching to
+ * @param propertyKey - The name of the method to cache
+ * @param opts - Cache configuration options
+ *
+ * @remarks
+ * - Must be called after the class is marked as `@Injectable()` or `injectable()`
+ * - The class must be registered in the DI container
+ * - Prefer using the `@Cache` decorator when possible for better readability
+ *
+ * @see {@link Cache} decorator for the declarative approach
+ * @see {@link DirectusCacheInterceptor} for implementation details
+ */
+export declare function useDirectusCache<K, Props = keyof K>(token: Type<K>, propertyKey: Props, opts: DirectusCacheOptions): void;

package/lib/types/services/DirectusContextService.d.ts

@@ -0,0 +1,149 @@
+import type { EndpointExtensionContext, HookExtensionContext, Item, OperationContext } from "@directus/types";
+type DirectusContext = EndpointExtensionContext | OperationContext | HookExtensionContext;
+/**
+ * Service to manage and access Directus context within Ts.ED dependency injection container.
+ *
+ * This service provides a bridge between Directus extensions and Ts.ED's DI system,
+ * allowing you to access the Directus context and its services from anywhere in your code.
+ *
+ * The context is automatically set by `wrapEndpoint`, `wrapOperation`, and `defineHook`
+ * wrappers, making it available through the DI container.
+ *
+ * ### Accessing context in a custom service
+ *
+ * ```ts
+ * import {Injectable} from "@tsed/di";
+ * import {DirectusContextService} from "@tsed/directus-sdk";
+ *
+ * @Injectable()
+ * export class MyService {
+ *   directusContext = inject(DirectusContextService);
+ *
+ *   async doSomething() {
+ *     const context = this.directusContext.get();
+ *     const schema = await context.getSchema();
+ *     // Use schema...
+ *   }
+ * }
+ * ```
+ *
+ * ### Using inject() to get the service
+ *
+ * ```ts
+ * import {inject} from "@tsed/di";
+ * import {DirectusContextService} from "@tsed/directus-sdk";
+ *
+ * const contextService = inject(DirectusContextService);
+ * const context = contextService.get();
+ *```
+ *
+ * @remarks
+ * This service is automatically registered as injectable and can be accessed via `inject()`.
+ */
+export declare class DirectusContextService {
+    /**
+     * Sets the Directus context in the current DI context.
+     *
+     * This method is typically called internally by the wrapper functions
+     * (`wrapEndpoint`, `wrapOperation`, `defineHook`) and should not be
+     * called manually in most cases.
+     *
+     * @param ctx - The Directus extension context (endpoint, operation, or hook)
+     *
+     * @example
+     * ```ts
+     * const contextService = inject(DirectusContextService);
+     * contextService.set(directusContext);
+     * ```
+     */
+    set(ctx: DirectusContext): void;
+    /**
+     * Retrieves the Directus context from the current DI context.
+     *
+     * Returns the context that was previously set by the wrapper functions.
+     * This allows you to access Directus services, schema, logger, and other
+     * context-specific functionality.
+     *
+     * ### Accessing context properties
+     *
+     * ```ts
+     * const contextService = inject(DirectusContextService);
+     * const context = contextService.get();
+     *
+     * // Access logger
+     * context.logger.info("Message");
+     *
+     * // Access schema
+     * const schema = await context.getSchema();
+     *
+     * // Access services
+     * const itemsService = new context.services.ItemsService("users");
+     * ```
+     *
+     * @returns The Directus extension context, or undefined if not set
+     *
+     */
+    get(): DirectusContext;
+    /**
+     * Creates and returns an ItemsService instance for the specified collection.
+     *
+     * This is a convenience method that:
+     *
+     * 1. Retrieves the Directus context
+     * 2. Fetches the database schema
+     * 3. Creates an ItemsService with the schema and provided options
+     *
+     * The ItemsService allows you to perform CRUD operations on Directus collections.
+     *
+     * ### Basic usage
+     *
+     * ```ts
+     * const contextService = inject(DirectusContextService);
+     * const usersService = await contextService.getItemsService("users");
+     *
+     * // Read all users
+     * const users = await usersService.readByQuery({ limit: -1 });
+     *
+     * // Create a user
+     * const userId = await usersService.createOne({ name: "John", email: "john@example.com" });
+     * ```
+     *
+     * ### With typed collection
+     *
+     * ```ts
+     * type User = Item & {
+     *   id: string;
+     *   name: string;
+     *   email: string;
+     * };
+     *
+     * const contextService = inject(DirectusContextService);
+     * const usersService = await contextService.getItemsService<User, "users">("users");
+     *
+     * // Now fully typed
+     * const users: User[] = await usersService.readByQuery({ limit: -1 });
+     * ```
+     *
+     * ### With accountability options
+     *
+     * ```ts
+     * const contextService = inject(DirectusContextService);
+     * const itemsService = await contextService.getItemsService("articles", {
+     *   accountability: {
+     *     user: "user-id",
+     *     role: "admin"
+     *   }
+     * });
+     * ```
+     *
+     * @template T - The item type extending Directus Item
+     * @template Collection - The collection name as a string literal type
+     * @param collection - The name of the collection to access
+     * @param options - Additional options for the ItemsService (e.g., accountability, knex instance)
+     * @returns A promise resolving to an ItemsService instance for the collection
+     * @throws {Error} If no Directus context is available (called outside extension context)
+     * @see {@link DirectusItemsRepository} for a more structured way to work with collections
+     */
+    getItemsService<T extends Item = Item, Collection extends string = string>(collection: Collection, options?: any): Promise<import("@directus/types").AbstractService<T>>;
+}
+export {};