@tsed/directus-sdk 8.19.0

package/.barrelsby.json

@@ -0,0 +1,5 @@
+{
+  "directory": ["./src"],
+  "exclude": ["**/bin", "**/__mock__", "**/__mocks__", "**/*.spec.ts"],
+  "delete": true
+}

package/lib/esm/bootstrap/attach-logger.js

@@ -0,0 +1,25 @@
+import "@tsed/logger-connect";
+import { useLogger } from "@directus/api/logger/index";
+import { attachLogger } from "@tsed/di";
+import { $log } from "@tsed/logger";
+const cmsLogger = useLogger();
+function print(o) {
+    if (o?.data?.length && typeof o?.data[0] === "string") {
+        return o?.data[0];
+    }
+    return JSON.stringify(o, null, 2);
+}
+$log.appenders.clear();
+$log.appenders.set("stdout", {
+    type: "connect",
+    options: {
+        logger: {
+            info: (o) => cmsLogger.info(print(o)),
+            warn: (o) => cmsLogger.warn(print(o)),
+            debug: (o) => cmsLogger.debug(print(o)),
+            trace: (o) => cmsLogger.trace(print(o)),
+            error: (o) => cmsLogger.error(print(o))
+        }
+    }
+});
+attachLogger($log);

package/lib/esm/bootstrap/runtime.js

@@ -0,0 +1,11 @@
+import "./attach-logger.js";
+import { withOptions } from "@tsed/config";
+import { EnvsConfigSource } from "@tsed/config/envs";
+import { configuration } from "@tsed/di";
+configuration().set({
+    extends: [
+        withOptions(EnvsConfigSource, {
+            name: "envs"
+        })
+    ]
+});

package/lib/esm/decorators/cache.js

@@ -0,0 +1,60 @@
+import { Intercept } from "@tsed/di";
+import { DirectusCacheInterceptor } from "../services/DirectusCacheInterceptor.js";
+/**
+ * Decorator to cache method results using Directus cache system.
+ *
+ * This decorator uses the Directus cache infrastructure (system cache by default) to store
+ * method results. Cached values are retrieved on subsequent calls with the same arguments,
+ * avoiding redundant computations or API calls.
+ *
+ * ### Basic usage
+ *
+ * ```ts
+ * import {Injectable} from "@tsed/di";
+ * import {Cache} from "@tsed/directus-sdk";
+ *
+ * @Injectable()
+ * export class JiraIssueClient {
+ *   // Cache search results for 15 minutes (default TTL)
+ *   @Cache({ ttl: 900000 })
+ *   search(query: string) {
+ *     // Expensive API call
+ *     return this.fetchFromJira(query);
+ *   }
+ *
+ *   // Custom cache key generator
+ *   @Cache({
+ *     ttl: 60000,
+ *     keyGenerator: (userId: string) => `user:${userId}`
+ *   })
+ *   getUserById(userId: string) {
+ *     return this.fetchUser(userId);
+ *   }
+ *
+ *   // Use regular cache instead of system cache
+ *   @Cache({
+ *     ttl: 300000,
+ *     useSystemCache: false,
+ *     namespace: "custom:namespace"
+ *   })
+ *   getCustomData() {
+ *     return this.fetchCustomData();
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Cache configuration options
+ * @param options.ttl - Time to live in milliseconds (default: 900000ms = 15 minutes)
+ * @param options.keyGenerator - Custom function to generate cache keys from method arguments
+ * @param options.namespace - Custom namespace for cache keys (default: className:methodName)
+ * @param options.useSystemCache - Whether to use system cache (true) or regular cache (false). Default: true
+ *
+ * @returns A method decorator that intercepts method calls and caches results
+ *
+ * @decorator
+ * @see {@link DirectusCacheInterceptor} for implementation details
+ * @see {@link DirectusCacheOptions} for available options
+ */
+export function Cache(options) {
+    return Intercept(DirectusCacheInterceptor, options);
+}

package/lib/esm/fn/defineEndpoint.js

@@ -0,0 +1,82 @@
+import { defineEndpoint as oDefineEndpoint } from "@directus/extensions-sdk";
+import { wrapEndpoint } from "./wrapEndpoint.js";
+/**
+ * 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 function defineEndpoint(config) {
+    if (typeof config === "function") {
+        return oDefineEndpoint(wrapEndpoint(config));
+    }
+    return oDefineEndpoint({
+        ...config,
+        handler: wrapEndpoint(config.handler)
+    });
+}

package/lib/esm/fn/defineHook.js

@@ -0,0 +1,134 @@
+import "../bootstrap/runtime.js";
+import { DIContext, inject, injector, runInContext } from "@tsed/di";
+import { nanoid } from "nanoid";
+import { DirectusContextService } from "../services/DirectusContextService.js";
+/**
+ * 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 function defineHook(callback) {
+    return async (register, context) => {
+        await injector().load();
+        const $ctx = new DIContext({
+            id: nanoid(),
+            platform: "DIRECTUS_HOOK",
+            maxStackSize: 0
+        });
+        return runInContext($ctx, async () => {
+            try {
+                inject(DirectusContextService).set(context);
+                return await callback(register, context);
+            }
+            catch (error) {
+                $ctx.logger.error({
+                    error_name: error.name,
+                    error_message: error.message,
+                    error_description: error.description,
+                    error_stack: error.stack
+                });
+                throw error;
+            }
+            finally {
+                $ctx.logger.flush();
+            }
+        });
+    };
+}

package/lib/esm/fn/defineOperationApi.js

@@ -0,0 +1,120 @@
+import { defineOperationApi as oDefineOperationApi } from "@directus/extensions-sdk";
+import { wrapOperation } from "./wrapOperation.js";
+/**
+ * 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 function defineOperationApi(config) {
+    return oDefineOperationApi({
+        ...config,
+        handler: wrapOperation(config.handler)
+    });
+}

package/lib/esm/fn/wrapEndpoint.js

@@ -0,0 +1,80 @@
+import "../bootstrap/runtime.js";
+import { attachLogger, DIContext, inject, injector, runInContext } from "@tsed/di";
+import { nanoid } from "nanoid";
+import { DirectusContextService } from "../services/DirectusContextService.js";
+const VERBS = ["get", "put", "post", "delete", "head", "use", "all", "options"];
+/**
+ * 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 function wrapEndpoint(callback) {
+    return (router, context) => {
+        attachLogger(context.logger);
+        VERBS.forEach((verb) => {
+            const r = router;
+            if (r[verb] && !r["__" + verb]) {
+                r["__" + verb] = r[verb];
+                r[verb] = (path, handler) => {
+                    const wrapped = async (req, res) => {
+                        await injector().load();
+                        const $ctx = new DIContext({
+                            id: nanoid(),
+                            platform: "DIRECTUS_ENDPOINT",
+                            maxStackSize: 0
+                        });
+                        return runInContext($ctx, async () => {
+                            inject(DirectusContextService).set(context);
+                            try {
+                                return await handler(req, res);
+                            }
+                            catch (error) {
+                                res.status(error.status || 500).json({
+                                    message: error.error_message || error.message || "Internal Server Error",
+                                    errors: error.errors
+                                });
+                                $ctx.logger.error({
+                                    error_name: error.name,
+                                    error_message: error.message,
+                                    error_description: error.description,
+                                    error_stack: error.stack
+                                });
+                            }
+                            finally {
+                                $ctx.logger.flush();
+                            }
+                        });
+                    };
+                    r["__" + verb](path, wrapped);
+                };
+            }
+        });
+        callback(router, context);
+    };
+}

package/lib/esm/fn/wrapOperation.js

@@ -0,0 +1,63 @@
+import "../bootstrap/runtime.js";
+import { DIContext, inject, injector, runInContext } from "@tsed/di";
+import { nanoid } from "nanoid";
+import { DirectusContextService } from "../services/DirectusContextService.js";
+/**
+ * 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 function wrapOperation(callback) {
+    return async (options, context) => {
+        await injector().load();
+        const $ctx = new DIContext({
+            id: nanoid(),
+            platform: "DIRECTUS_OPERATION",
+            maxStackSize: 0
+        });
+        return runInContext($ctx, async () => {
+            try {
+                inject(DirectusContextService).set(context);
+                return await callback(options, context);
+            }
+            catch (error) {
+                $ctx.logger.error({
+                    error_name: error.name,
+                    error_message: error.message,
+                    error_description: error.description,
+                    error_stack: error.stack
+                });
+            }
+            finally {
+                $ctx.logger.flush();
+            }
+        });
+    };
+}

package/lib/esm/index.js

@@ -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";