@tsed/directus-sdk 8.19.0

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

@@ -0,0 +1,226 @@
+import type { Item, MutationOptions } from "@directus/types";
+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 declare abstract class DirectusItemsRepository<T extends Item = Item, Collection extends string = string> {
+    protected contextService: DirectusContextService;
+    protected abstract collection: Collection;
+    /**
+     * 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(): Promise<import("@directus/types").AbstractService<T>>;
+    /**
+     * 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
+     */
+    create(data: Partial<T>, opts?: MutationOptions): Promise<T>;
+    /**
+     * 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
+     */
+    update(data: Partial<T> & Pick<T, "id">, opts?: MutationOptions): Promise<T>;
+    /**
+     * 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.
+     *
+     */
+    listAll(): Promise<T[]>;
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tsed/directus-sdk",
+  "description": "A library to integrate Directus SDK with Ts.ED, facilitating the creation of extensions (endpoints, hooks, operations) and the use of Directus services.",
+  "type": "module",
+  "version": "8.19.0",
+  "source": "./src/index.ts",
+  "main": "./lib/esm/index.js",
+  "module": "./lib/esm/index.js",
+  "typings": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "tsed-source": "./src/index.ts",
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "default": "./lib/esm/index.js"
+    },
+    "./attach-logger": {
+      "tsed-source": "./src/bootstrap/attach-logger.ts",
+      "types": "./lib/types/bootstrap/attach-logger.d.ts",
+      "import": "./lib/esm/bootstrap/attach-logger.js",
+      "default": "./lib/esm/bootstrap/attach-logger.js"
+    }
+  },
+  "scripts": {
+    "build": "yarn barrels && yarn build:ts",
+    "barrels": "barrels",
+    "test": "vitest run",
+    "build:ts": "tsc --build tsconfig.esm.json",
+    "test:ci": "vitest run --coverage.thresholds.autoUpdate=true"
+  },
+  "dependencies": {
+    "semver": "^7.6.3",
+    "tslib": "2.8.1"
+  },
+  "devDependencies": {
+    "@directus/api": "32.1.0",
+    "@directus/extensions-sdk": "13.1.1",
+    "@directus/sdk": "20.2.0",
+    "@directus/types": "13.4.0",
+    "@tsed/barrels": "8.19.0",
+    "@tsed/logger-connect": "8.0.4",
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "@directus/api": ">=31.0.0",
+    "@directus/extensions-sdk": ">=13.0.0",
+    "@directus/sdk": ">=20.0.0",
+    "@directus/types": ">=13.0.0",
+    "@tsed/config": ">=8.0.0",
+    "@tsed/core": ">=8.0.0",
+    "@tsed/di": ">=8.0.0",
+    "@tsed/logger": ">=8.0.0",
+    "@tsed/logger-connect": ">=8.0.0",
+    "express": "*"
+  },
+  "repository": "https://github.com/tsedio/tsed",
+  "bugs": {
+    "url": "https://github.com/tsedio/tsed/issues"
+  },
+  "homepage": "https://github.com/tsedio/tsed/tree/production/packages/third-parties/directus-sdk",
+  "author": "Romain Lenzotti",
+  "license": "MIT"
+}