@tsed/directus-sdk 8.19.0

package/lib/esm/services/DirectusCacheInterceptor.js

@@ -0,0 +1,184 @@
+import { getCache, getCacheValue, setCacheValue } from "@directus/api/cache";
+import { classOf } from "@tsed/core/utils/classOf.js";
+import { nameOf } from "@tsed/core/utils/nameOf.js";
+import { bindIntercept, injectable } from "@tsed/di";
+import { snakeCase } from "lodash";
+/**
+ * Default cache key generator that serializes method arguments into a cache key.
+ *
+ * Creates a JSON string of the arguments, or an empty string if no arguments.
+ * This ensures unique cache keys for different argument combinations.
+ *
+ * @param args - The method arguments to serialize
+ * @returns A string representation of the arguments, prefixed with ':'
+ *
+ * @example
+ * ```ts
+ * defaultKeyGenerator("user", 123)
+ * // Returns: ':["user",123]'
+ *
+ * defaultKeyGenerator()
+ * // Returns: ':'
+ * ```
+ */
+function defaultKeyGenerator(...args) {
+    return args.length > 0 ? JSON.stringify(args) : "";
+}
+/**
+ * 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 class DirectusCacheInterceptor {
+    /**
+     * 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
+     */
+    async intercept(context) {
+        const { ttl = 900000, // 15 minutes default
+        keyGenerator = defaultKeyGenerator, namespace = snakeCase(nameOf(context.target)) + ":" + String(context.propertyKey), useSystemCache = true } = context.options || {};
+        // Get appropriate cache instance
+        const cache = getCache();
+        const cacheInstance = useSystemCache ? cache.systemCache : cache.cache;
+        // Generate cache key
+        const cacheKey = `${namespace}:${keyGenerator(...context.args)}`;
+        // Try to get from cache
+        const cachedValue = await getCacheValue(cacheInstance, cacheKey);
+        if (cachedValue !== undefined) {
+            return cachedValue;
+        }
+        // Execute function and cache result
+        const result = await context.next();
+        await setCacheValue(cacheInstance, cacheKey, result, ttl);
+        return result;
+    }
+}
+injectable(DirectusCacheInterceptor);
+/**
+ * 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 function useDirectusCache(token, propertyKey, opts) {
+    bindIntercept(classOf(token), propertyKey, DirectusCacheInterceptor, opts);
+}

package/lib/esm/services/DirectusContextService.js

@@ -0,0 +1,162 @@
+import { context, injectable } from "@tsed/di";
+/**
+ * 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 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) {
+        context().set("DIRECTUS_CONTEXT", ctx);
+    }
+    /**
+     * 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() {
+        return context().get("DIRECTUS_CONTEXT");
+    }
+    /**
+     * 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
+     */
+    async getItemsService(collection, options = {}) {
+        const context = this.get();
+        if (context) {
+            const schema = await context.getSchema();
+            return new context.services.ItemsService(collection, {
+                ...options,
+                schema
+            });
+        }
+        throw new Error("No directus context available");
+    }
+}
+injectable(DirectusContextService);

package/lib/esm/services/DirectusItemsRepository.js

@@ -0,0 +1,240 @@
+import { inject } from "@tsed/di";
+import { DirectusContextService } from "./DirectusContextService.js";
+/**
+ * Abstract base class for creating typed repository patterns with Directus collections.
+ *
+ * This class provides a structured way to interact with Directus collections by:
+ * - Automatically retrieving the Directus context via dependency injection
+ * - Providing common CRUD operations (create, update, listAll)
+ * - Supporting custom methods through inheritance
+ * - Ensuring type safety with TypeScript generics
+ *
+ * Extend this class to create collection-specific repositories with custom business logic.
+ *
+ * ### Basic repository with custom methods
+ * ```ts
+ * import {injectable} from "@tsed/di";
+ * import {DirectusItemsRepository} from "@tsed/directus-sdk";
+ * import type {Item} from "@directus/types";
+ *
+ * type Release = Item & {
+ *   id: string;
+ *   title: string;
+ *   status: "draft" | "published";
+ *   publishedAt?: string;
+ * };
+ *
+ * export class ReleasesRepository extends DirectusItemsRepository<Release, "releases"> {
+ *   protected collection = "releases" as const;
+ *
+ *   async getPublishedReleases() {
+ *     const collection = await this.getCollection();
+ *
+ *     return collection.readByQuery({
+ *       filter: {
+ *         status: {
+ *           _eq: "published"
+ *         }
+ *       },
+ *       sort: ["-publishedAt"]
+ *     });
+ *   }
+ *
+ *   async publishRelease(id: string) {
+ *     return this.update({
+ *       id,
+ *       status: "published",
+ *       publishedAt: new Date().toISOString()
+ *     });
+ *   }
+ * }
+ * injectable(ReleasesRepository)
+ * ```
+ *
+ * ### Repository with complex queries
+ *
+ * ```ts
+ * import {injectable} from "@tsed/di";
+ * import {DirectusItemsRepository} from "@tsed/directus-sdk";
+ *
+ * export class ArticlesRepository extends DirectusItemsRepository<Article, "articles"> {
+ *   protected collection = "articles" as const;
+ *
+ *   async findByAuthor(authorId: string) {
+ *     const collection = await this.getCollection();
+ *
+ *     return collection.readByQuery({
+ *       filter: {
+ *         author: {
+ *           _eq: authorId
+ *         }
+ *       }
+ *     });
+ *   }
+ *
+ *   async searchByTitle(query: string) {
+ *     const collection = await this.getCollection();
+ *
+ *     return collection.readByQuery({
+ *       filter: {
+ *         title: {
+ *           _contains: query
+ *         }
+ *       }
+ *     });
+ *   }
+ * }
+ * injectable(ArticlesRepository);
+ * ```
+ *
+ * ### Using repository in an endpoint
+ *
+ * ```ts
+ * import {defineEndpoint} from "@tsed/directus-sdk";
+ * import {inject} from "@tsed/di";
+ *
+ * export default defineEndpoint({
+ *   id: "releases-api",
+ *   handler: (router) => {
+ *     const releasesRepo = inject(ReleasesRepository);
+ *
+ *     router.get("/releases", async (req, res) => {
+ *       const releases = await releasesRepo.getPublishedReleases();
+ *       res.json(releases);
+ *     });
+ *
+ *     router.post("/releases/:id/publish", async (req, res) => {
+ *       const release = await releasesRepo.publishRelease(req.params.id);
+ *       res.json(release);
+ *     });
+ *   }
+ * });
+ * ```
+ *
+ * @template T - The item type extending Directus Item interface
+ * @template Collection - The collection name as a string literal type
+ *
+ * @remarks
+ * - The extending class must define the `collection` property
+ * - Don't forget to mark the extending class with `@Injectable()` or `injectable()`
+ * - Access to Directus context is automatically handled through `DirectusContextService`
+ *
+ * @see {@link DirectusContextService} for lower-level access to Directus context
+ */
+export class DirectusItemsRepository {
+    constructor() {
+        this.contextService = inject(DirectusContextService);
+    }
+    /**
+     * Retrieves the Directus ItemsService for the configured collection.
+     *
+     * This method provides access to the underlying Directus ItemsService,
+     * which offers full CRUD capabilities and advanced query features.
+     *
+     * ```ts
+     * const collection = await this.getCollection();
+     * const items = await collection.readByQuery({
+     *   filter: { status: { _eq: "active" } },
+     *   limit: 10,
+     *   offset: 0
+     * });
+     * ```
+     *
+     * @returns A promise resolving to the ItemsService for the collection
+     *
+     */
+    getCollection() {
+        return this.contextService.getItemsService(this.collection);
+    }
+    /**
+     * Creates a new item in the collection and returns the created item.
+     *
+     * ```ts
+     * const newRelease = await releasesRepo.create({
+     *   title: "Version 1.0",
+     *   status: "draft"
+     * });
+     *
+     * console.log(newRelease.id); // Auto-generated ID
+     * ```
+     *
+     * ### With mutation options
+     *
+     * ```ts
+     * const item = await repo.create(data, {
+     *   emitEvents: false,
+     *   bypassLimits: true
+     * });
+     * ```
+     *
+     * @param data - Partial item data to create
+     * @param opts - Optional mutation options (e.g., emitEvents, bypassLimits)
+     *
+     * @returns A promise resolving to the created item with all fields
+     */
+    async create(data, opts) {
+        const collection = await this.getCollection();
+        const key = await collection.createOne(data, opts);
+        return collection.readOne(key);
+    }
+    /**
+     * Updates an existing item in the collection and returns the updated item.
+     *
+     * ```ts
+     * const updated = await releasesRepo.update({
+     *   id: "release-123",
+     *   status: "published"
+     * });
+     * ```
+     *
+     * ### With mutation options
+     *
+     * ```ts
+     * const updated = await repo.update(
+     *   { id: "123", title: "New Title" },
+     *   { emitEvents: true }
+     * );
+     * ```
+     *
+     * @param data - Partial item data including the required `id` field
+     * @param opts - Optional mutation options (e.g., emitEvents, bypassLimits)
+     *
+     * @returns A promise resolving to the updated item
+     */
+    async update(data, opts) {
+        const collection = await this.getCollection();
+        const key = await collection.updateOne(data.id, data, opts);
+        return collection.readOne(key);
+    }
+    /**
+     * Retrieves all items from the collection without pagination.
+     *
+     * ```ts
+     * const allReleases = await releasesRepo.listAll();
+     * console.log(`Total releases: ${allReleases.length}`);
+     * ```
+     *
+     * ### For large collections, consider custom pagination
+     *
+     * ```ts
+     * async getPaginatedItems(page: number, pageSize: number) {
+     *   const collection = await this.getCollection();
+     *   return collection.readByQuery({
+     *     limit: pageSize,
+     *     offset: (page - 1) * pageSize
+     *   });
+     * }
+     * ```
+     *
+     * @returns A promise resolving to an array of all items in the collection
+     *
+     * @remarks
+     * This method uses `limit: -1` to retrieve all items. Use with caution on
+     * large collections as it may impact performance.
+     *
+     */
+    async listAll() {
+        const service = await this.getCollection();
+        return (await service.readByQuery({ limit: -1 }));
+    }
+}

package/lib/types/bootstrap/attach-logger.d.ts

@@ -0,0 +1 @@
+import "@tsed/logger-connect";

package/lib/types/bootstrap/runtime.d.ts

@@ -0,0 +1 @@
+import "./attach-logger.js";

package/lib/types/decorators/cache.d.ts

@@ -0,0 +1,57 @@
+import { type DirectusCacheOptions } 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 declare function Cache(options: DirectusCacheOptions): any;