feat(cli): add excludeCollections and onlyCollections options (#52)

* feat(cli): can exclude or include collections from process

* chore(cli): run prettier

* test(e2e): add excludeSomeCollections

* test(e2e): add tests on push with exclusions

* refactor(e2e): rename folder

* test(e2e): add includeSomeCollections

* fix(cli): change entrypoint

* docs: explain onlyCollections and excludeCollections options

README.md

@@ -170,6 +170,12 @@ These options can be used with any command to configure the operation of `direct
 - `--no-specs`  
   Do not dump the specifications (GraphQL & OpenAPI). By default, specifications are dumped.
 
+- `-o, --only-collections <onlyCollections>`
+  Comma-separated list of directus collections to include during `pull` `push` or `diff` process.
+
+- `-x, --exclude-collections <excludeCollections>`  
+  Comma-separated list of directus collections to exclude during `pull` `push` or `diff`. Can be used along with `only-collections`.
+
 - `-h, --help`  
   Display help information for the `directus-sync` commands.
 
@@ -201,6 +207,8 @@ module.exports = {
   snapshotPath: 'snapshot',
   specsPath: 'specs',
   specs: true,
+  onlyCollections: ['roles', 'permissions', 'settings'],
+  excludeCollections: ['settings'],
 };
 ```
 

packages/cli/bin/index.js

@@ -1,3 +1,2 @@
 #! /usr/bin/env node
-const { run } = require('../dist');
-void run();
+require('../dist/entrypoint');

packages/cli/package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "start": "ts-node src/index.ts",
+    "start": "ts-node src/entrypoint.ts",
     "test": "jest",
     "prepublishOnly": "cp ../../README.md ./README.md"
   },
@@ -25,6 +25,7 @@
     "@types/jest": "^29.5.12",
     "@types/node": "20.11.25",
     "jest": "^29.7.0",
+    "ts-essentials": "^9.4.2",
     "ts-jest": "^29.1.2",
     "ts-node": "10.9.2",
     "typescript": "5.4.2"

packages/cli/src/entrypoint.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+import 'dotenv/config';
+
+import { run } from './run';
+
+void run();

packages/cli/src/index.ts

@@ -1,5 +1,4 @@
 import 'reflect-metadata';
-import 'dotenv/config';
 
 export * from './lib';
 export * from './run';

packages/cli/src/lib/loader.ts

@@ -1,4 +1,6 @@
+import { DictionaryValues } from 'ts-essentials';
 import {
+  CollectionRecord,
   ConfigService,
   DashboardsCollection,
   FlowsCollection,
@@ -13,7 +15,7 @@ import {
   WebhooksCollection,
 } from './services';
 import { createDumpFolders, getPinoTransport } from './helpers';
-import { Container } from 'typedi';
+import { Container, Token } from 'typedi';
 import Logger from 'pino';
 import { LOGGER } from './constants';
 
@@ -53,17 +55,39 @@ export function disposeContext() {
 export function loadCollections() {
   // The order of the collections is important
   // The collections are populated in the same order
-  return [
-    Container.get(SettingsCollection),
-    Container.get(FoldersCollection),
-    Container.get(TranslationsCollection),
-    Container.get(WebhooksCollection),
-    Container.get(FlowsCollection),
-    Container.get(OperationsCollection),
-    Container.get(RolesCollection),
-    Container.get(PermissionsCollection),
-    Container.get(DashboardsCollection),
-    Container.get(PanelsCollection),
-    Container.get(PresetsCollection),
-  ];
+  const collectionsConstructors = {
+    settings: SettingsCollection,
+    folders: FoldersCollection,
+    translations: TranslationsCollection,
+    webhooks: WebhooksCollection,
+    flows: FlowsCollection,
+    operations: OperationsCollection,
+    roles: RolesCollection,
+    permissions: PermissionsCollection,
+    dashboards: DashboardsCollection,
+    panels: PanelsCollection,
+    presets: PresetsCollection,
+  } as const satisfies CollectionRecord<unknown>;
+  type CollectionInstance = InstanceType<
+    DictionaryValues<typeof collectionsConstructors>
+  >;
+
+  // Get the collections to process
+  const config = Container.get(ConfigService);
+  const collectionsToProcess = config.getCollectionsToProcess();
+
+  // Initialize the collections
+  const output: CollectionInstance[] = [];
+  for (const collection of collectionsToProcess) {
+    const collectionConstructor = collectionsConstructors[collection];
+    output.push(
+      Container.get(
+        collectionConstructor as Token<
+          InstanceType<typeof collectionConstructor>
+        >,
+      ),
+    );
+  }
+
+  return output;
 }

packages/cli/src/lib/program.ts

@@ -54,6 +54,13 @@ function getVersion(): string {
   }
 }
 
+/**
+ * Split a comma separated list
+ */
+function commaSeparatedList(value: string) {
+  return value.split(',').map((v) => v.trim());
+}
+
 export function createProgram() {
   const program = createCommand();
   // Global options
@@ -113,6 +120,14 @@ export function createProgram() {
     '--no-specs',
     `should dump the GraphQL & OpenAPI specifications (default "${DefaultConfig.specs}")`,
   );
+  const excludeCollectionsOption = new Option(
+    '-x, --exclude-collections <excludeCollections>',
+    `comma separated list of collections to exclude from the process`,
+  ).argParser(commaSeparatedList);
+  const onlyCollectionsOption = new Option(
+    '-o, --only-collections <onlyCollections>',
+    `comma separated list of collections to include in the process`,
+  ).argParser(commaSeparatedList);
 
   program
     .version(getVersion())
@@ -132,6 +147,8 @@ export function createProgram() {
     .addOption(snapshotPathOption)
     .addOption(noSpecificationsOption)
     .addOption(specificationsPathOption)
+    .addOption(excludeCollectionsOption)
+    .addOption(onlyCollectionsOption)
     .action(wrapAction(program, runPull));
 
   program
@@ -144,6 +161,8 @@ export function createProgram() {
     .addOption(collectionsPathOption)
     .addOption(snapshotPathOption)
     .addOption(forceOption)
+    .addOption(excludeCollectionsOption)
+    .addOption(onlyCollectionsOption)
     .action(wrapAction(program, runDiff));
 
   program
@@ -154,6 +173,8 @@ export function createProgram() {
     .addOption(collectionsPathOption)
     .addOption(snapshotPathOption)
     .addOption(forceOption)
+    .addOption(excludeCollectionsOption)
+    .addOption(onlyCollectionsOption)
     .action(wrapAction(program, runPush));
 
   program

packages/cli/src/lib/services/config/config.ts

@@ -3,7 +3,7 @@ import {
   ConfigFileOptions,
   DirectusConfigWithCredentials,
   DirectusConfigWithToken,
-  HookCollectionName,
+  CollectionName,
   Hooks,
   OptionName,
   Options,
@@ -14,7 +14,7 @@ import { ConfigFileLoader } from './config-file-loader';
 import { zodParse } from '../../helpers';
 import deepmerge from 'deepmerge';
 import { DefaultConfig, DefaultConfigPaths } from './default-config';
-import { OptionsSchema } from './schema';
+import { CollectionsList, OptionsSchema } from './schema';
 
 @Service()
 export class ConfigService {
@@ -100,14 +100,22 @@ export class ConfigService {
   }
 
   @Cacheable()
-  getHooksConfig(collection: HookCollectionName): Hooks {
+  getHooksConfig(collection: CollectionName): Hooks {
     const hooks = this.getOptions('hooks');
     if (!hooks) {
       return {};
     }
     return (hooks[collection] ?? {}) as Hooks;
   }
 
+  @Cacheable()
+  getCollectionsToProcess() {
+    const exclude = this.requireOptions('excludeCollections');
+    const only = this.requireOptions('onlyCollections');
+    const list = only.length > 0 ? only : CollectionsList;
+    return list.filter((collection) => !exclude.includes(collection));
+  }
+
   protected getOptions<T extends OptionName>(name: T): Options[T] | undefined {
     const options = this.flattenOptions();
     return options[name];

packages/cli/src/lib/services/config/default-config.ts

@@ -16,6 +16,8 @@ export const DefaultConfig: Pick<
   | 'force'
   | 'specs'
   | 'specsPath'
+  | 'excludeCollections'
+  | 'onlyCollections'
 > = {
   // Global
   debug: false,
@@ -29,4 +31,7 @@ export const DefaultConfig: Pick<
   specsPath: 'specs',
   // Diff, push
   force: false,
+  // Exclusion and Inclusion
+  excludeCollections: [],
+  onlyCollections: [],
 };

packages/cli/src/lib/services/config/interfaces.ts

@@ -2,8 +2,8 @@ import type { z } from 'zod';
 import type {
   ConfigFileOptionsSchema,
   OptionsFields,
-  OptionsHooksSchema,
   OptionsSchema,
+  CollectionEnum,
 } from './schema';
 import type { MigrationClient } from '../migration-client';
 import type { DirectusBaseType, Query } from '../collections';
@@ -14,7 +14,11 @@ export type Options = z.infer<typeof OptionsSchema>;
 
 export type ConfigFileOptions = z.infer<typeof ConfigFileOptionsSchema>;
 
-export type HookCollectionName = keyof typeof OptionsHooksSchema.shape;
+export type CollectionName = z.infer<typeof CollectionEnum>;
+
+export type CollectionRecord<T> = {
+  [key in CollectionName]: T;
+};
 
 export type TransformDataFunction = <T = unknown>(
   data: T[],

packages/cli/src/lib/services/config/schema.ts

@@ -1,12 +1,27 @@
 import { z } from 'zod';
 
+export const CollectionsList = [
+  'dashboards',
+  'flows',
+  'folders',
+  'operations',
+  'panels',
+  'permissions',
+  'presets',
+  'roles',
+  'settings',
+  'translations',
+  'webhooks',
+] as const;
+
+export const CollectionEnum = z.enum(CollectionsList);
+
 export const HooksSchema = z.object({
   onLoad: z.function().optional(),
   onDump: z.function().optional(),
   onSave: z.function().optional(),
   onQuery: z.function().optional(),
 });
-
 export const OptionsHooksSchema = z.object({
   dashboards: HooksSchema.optional(),
   flows: HooksSchema.optional(),
@@ -19,7 +34,7 @@ export const OptionsHooksSchema = z.object({
   settings: HooksSchema.optional(),
   translations: HooksSchema.optional(),
   webhooks: HooksSchema.optional(),
-});
+} satisfies { [key in z.infer<typeof CollectionEnum>]: z.Schema });
 
 export const OptionsFields = {
   // Global
@@ -44,6 +59,9 @@ export const OptionsFields = {
   id: z.string().optional(),
   // Hooks
   hooks: OptionsHooksSchema.optional(),
+  // Exclusion and Inclusion
+  excludeCollections: z.array(CollectionEnum).optional(),
+  onlyCollections: z.array(CollectionEnum).optional(),
 };
 export const OptionsSchema = z.object(OptionsFields);
 
@@ -66,4 +84,7 @@ export const ConfigFileOptionsSchema = z.object({
   specsPath: OptionsFields.specsPath.optional(),
   // Hooks config
   hooks: OptionsHooksSchema.optional(),
+  // Exclusion and Inclusion
+  excludeCollections: OptionsFields.excludeCollections.optional(),
+  onlyCollections: OptionsFields.onlyCollections.optional(),
 });

packages/e2e/spec/entrypoint.spec.ts

@@ -19,6 +19,10 @@ import {
   onSave,
   onSaveDuplicate,
 } from './hooks/index.js';
+import {
+  excludeSomeCollections,
+  includeSomeCollections,
+} from './exclude-include/index.js';
 
 jasmine.DEFAULT_TIMEOUT_INTERVAL = 10000;
 
@@ -57,4 +61,7 @@ describe('Pull and check if ids are preserved for some collections', () => {
   onSaveDuplicate(context);
   onLoad(context);
   onQuery(context);
+
+  excludeSomeCollections(context);
+  includeSomeCollections(context);
 });