From 875d5834a108f86ffbbe1123f314a3c7481ad87a Mon Sep 17 00:00:00 2001 From: jeffladiray Date: Wed, 15 Dec 2021 17:34:20 +0100 Subject: [PATCH 1/3] docs: add schema type documentation --- .../src/interfaces/schema.ts | 41 ++++++++++++++++--- typedoc.json | 6 +-- 2 files changed, 37 insertions(+), 10 deletions(-) diff --git a/packages/datasource-toolkit/src/interfaces/schema.ts b/packages/datasource-toolkit/src/interfaces/schema.ts index 9688b5b3de..9e7f7cac32 100644 --- a/packages/datasource-toolkit/src/interfaces/schema.ts +++ b/packages/datasource-toolkit/src/interfaces/schema.ts @@ -1,17 +1,43 @@ import { Filter, Operator, Aggregator } from "./query/selection"; +/** + * Representation of a collection schema. + * + * It is used to generated the `.forestadmin-schema.json` file. + */ export type CollectionSchema = { - actions: Array<{ - name: string; - scope: "single" | "bulk" | "global"; - forceDownload?: boolean; - }>; + /* Declare action(s) associated with a collection. */ + actions: Array; + /* Declare the list of fields of the collection. */ fields: { [fieldName: string]: FieldSchema }; + /* When "true", the collection is searchable. */ searchable: boolean; + /* Declare a list of segment name. */ segments: string[]; + /* Declare a list of filters that every records should match. */ validation?: Filter; }; +/** + * Representation of an action schema. + */ +export type ActionSchema = { + /* Visible name of the action */ + name: string; + /** + * Scope of the action + * - "single" mean the action is visible only when a single record is selected + * - "bulk" mean the action is visible when more than one record is selected + * - "global" mean the action is visible only when no records are selected + */ + scope: "single" | "bulk" | "global"; + /* When "true", the action response will force a file download */ + forceDownload?: boolean; +}; + +/** + * + */ export type FieldSchema = | ColumnSchema | ManyToOneSchema @@ -19,6 +45,9 @@ export type FieldSchema = | OneToOneSchema | ManyToManySchema; +/** + * + */ export type ColumnSchema = { columnType: ColumnType; filterOperators: Set; @@ -61,6 +90,7 @@ export type ManyToManySchema = { export type ColumnType = PrimitiveTypes | { [key: string]: ColumnType } | [ColumnType]; +/* Enumeration of supported primitive types */ export enum PrimitiveTypes { Boolean = "Boolean", Date = "Date", @@ -74,6 +104,7 @@ export enum PrimitiveTypes { Uuid = "Uuid", } +/* Enumeration of supported field types */ export enum FieldTypes { Column = "Column", ManyToOne = "ManyToOne", diff --git a/typedoc.json b/typedoc.json index aa4e2440b5..685c64417b 100644 --- a/typedoc.json +++ b/typedoc.json @@ -3,11 +3,7 @@ "excludePrivate": true, "hideGenerator": true, "entryPointStrategy": "packages", - "entryPoints": [ - "packages/agent", - "packages/datasource-toolkit", - "packages/datasource-sequelize" - ], + "entryPoints": ["packages/agent", "packages/datasource-toolkit", "packages/datasource-sequelize"], "includes": [""], "out": "dist-docs" } From f8dc643eca6ce8122dda222c6801de4095ee38a8 Mon Sep 17 00:00:00 2001 From: jeffladiray Date: Thu, 16 Dec 2021 12:35:53 +0100 Subject: [PATCH 2/3] docs: try more things --- .../docs/datasource/index.md | 15 +++++ .../src/interfaces/collection.ts | 67 +++++++++++++++++++ .../src/interfaces/schema.ts | 62 +++++++++++------ 3 files changed, 122 insertions(+), 22 deletions(-) create mode 100644 packages/datasource-toolkit/docs/datasource/index.md diff --git a/packages/datasource-toolkit/docs/datasource/index.md b/packages/datasource-toolkit/docs/datasource/index.md new file mode 100644 index 0000000000..399c37ce35 --- /dev/null +++ b/packages/datasource-toolkit/docs/datasource/index.md @@ -0,0 +1,15 @@ +> **_NOTE:_** Implementing a Collection or a Datasource manually is an advanced notion. If you're just starting with Forest Admin, you should start your project with one of our existing Datasources. + +## Datasource + +### What is a datasource? + +A Datasource represent a list of [Collection](#collection). It is mainly used to aggregate multiples collections from an external source of data. + +## Collection + +### What is a Collection? + +A Collection is a set of data elements displayed in a Table view (by default), with rows (i.e. records) and columns (i.e. fields). A Collection has a specified number of columns, but can have any number of rows. + +> **_NOTE:_** Implementing a Collection manually is an advanced notion. If you're just starting with Forest Admin, you should skip this for now. diff --git a/packages/datasource-toolkit/src/interfaces/collection.ts b/packages/datasource-toolkit/src/interfaces/collection.ts index 572a8439b1..6a13367f5b 100644 --- a/packages/datasource-toolkit/src/interfaces/collection.ts +++ b/packages/datasource-toolkit/src/interfaces/collection.ts @@ -1,3 +1,6 @@ +/** + * [[include:packages/datasource-toolkit/docs/datasource/index.md]] + */ import { Action } from "./action"; import { AggregateResult, Aggregation } from "./query/aggregation"; import { Projection } from "./query/projection"; @@ -5,27 +8,91 @@ import { CompositeId, RecordData } from "./query/record"; import { PaginatedFilter, Filter } from "./query/selection"; import { CollectionSchema } from "./schema"; +/** + * Represent a datasource + * + * A datasource is a list of collections from a single source of data + */ export interface DataSource { + /** List of collections associated with the datasource */ get collections(): Collection[]; + + /** + * Get a collection by name from the datasource + * @params name The name of the collection + * @return The collection when found + */ getCollection(name: string): Collection; } +/** + * Represent a collection + */ export interface Collection { + /** The datasource the collection is associated with */ get dataSource(): DataSource; + /** Name of the collection */ get name(): string; + /** Schema of the collection */ get schema(): CollectionSchema; + /** + * Get an action by name + * + * @params name The name of the action to retrieve + * @return The action when it exists + */ getAction(name: string): Action; + /** + * Get record data by id + * + * @params id The requested record id + * @params projection The requested record projection + * @return An promise of a record data + */ getById(id: CompositeId, projection: Projection): Promise; + /** + * Create a list of records + * + * @params data An array of records data to create + * @return An promise containing the created record + */ create(data: RecordData[]): Promise; + /** + * List records based on specific list of filters + * + * @params filter A filter representing a selection of records to return + * @params projection The requested record projection + * @return An promise containing a list of records matching the parameters provided + */ list(filter: PaginatedFilter, projection: Projection): Promise; + /** + * Update a list of records + * + * @params filter A filter representing a selection of records to update + * @params patch The patch to apply of records selected by the filter + * @return An promise containing the list of records that were updated + */ update(filter: Filter, patch: RecordData): Promise; + /** + * Delete a list of records + * + * @params filter A filter representing a selection of records to delete + * @return An empty promise + */ delete(filter: Filter): Promise; + /** + * Aggregate filtered records + * + * @params filter A filter representing a selection of records to aggregate + * @params aggregation The aggregation operation + * @return The aggregated results + */ aggregate(filter: PaginatedFilter, aggregation: Aggregation): Promise; } diff --git a/packages/datasource-toolkit/src/interfaces/schema.ts b/packages/datasource-toolkit/src/interfaces/schema.ts index 9e7f7cac32..a126580b7c 100644 --- a/packages/datasource-toolkit/src/interfaces/schema.ts +++ b/packages/datasource-toolkit/src/interfaces/schema.ts @@ -1,43 +1,45 @@ import { Filter, Operator, Aggregator } from "./query/selection"; /** - * Representation of a collection schema. + * Schema representation of a collection * - * It is used to generated the `.forestadmin-schema.json` file. + * It is used to generated the `.forestadmin-schema.json` file */ export type CollectionSchema = { - /* Declare action(s) associated with a collection. */ + /** + * Declare action(s) associated with a collection + */ actions: Array; - /* Declare the list of fields of the collection. */ + /** Declare the list of fields of the collection */ fields: { [fieldName: string]: FieldSchema }; - /* When "true", the collection is searchable. */ + /** When "true", the collection is searchable */ searchable: boolean; - /* Declare a list of segment name. */ + /** Declare a list of segment name */ segments: string[]; - /* Declare a list of filters that every records should match. */ + /** + * Declare a filter that every records should match + */ validation?: Filter; }; /** - * Representation of an action schema. + * Schema representation of an action */ export type ActionSchema = { - /* Visible name of the action */ + /** Visible name of the action */ name: string; /** - * Scope of the action - * - "single" mean the action is visible only when a single record is selected - * - "bulk" mean the action is visible when more than one record is selected - * - "global" mean the action is visible only when no records are selected + * Scope of the action. + * - "single": the action is only available for one selected record at a time + * - "bulk": the action will be available when you click on one or several desired records + * - "global": the action is always available and will be executed on all records */ scope: "single" | "bulk" | "global"; - /* When "true", the action response will force a file download */ + /** When "true", the action response will force a file download */ forceDownload?: boolean; }; -/** - * - */ +/** Schema representation of a field */ export type FieldSchema = | ColumnSchema | ManyToOneSchema @@ -45,16 +47,20 @@ export type FieldSchema = | OneToOneSchema | ManyToManySchema; -/** - * - */ +/** Schema representation of a column */ export type ColumnSchema = { + /** Type of the column */ columnType: ColumnType; + /** List of all the supported operators */ filterOperators: Set; defaultValue?: unknown; + /** Array of possible values for the column */ enumValues?: string[]; + /** When "true", the column is considerer as a primary key */ isPrimaryKey?: boolean; + /** When "true", the column is considerer as a read-only */ isReadOnly?: boolean; + /** When "true", the column is considerer as a sortable */ isSortable?: boolean; type: FieldTypes.Column; validation?: @@ -62,26 +68,38 @@ export type ColumnSchema = { | { operator: Operator; field: string; value: unknown }; }; +/** Schema representation of a many to one relationship */ export type ManyToOneSchema = { + /** Targetted collection */ foreignCollection: string; + /** Targetted key of the collection */ foreignKey: string; type: FieldTypes.ManyToOne; }; +/** Schema representation of a one to many relationship */ export type OneToManySchema = { + /** Targetted collection */ foreignCollection: string; + /** Targetted key of the collection */ foreignKey: string; type: FieldTypes.OneToMany; }; +/** Schema representation of a one to one relationship */ export type OneToOneSchema = { + /** Targetted collection */ foreignCollection: string; + /** Targetted key of the collection */ foreignKey: string; type: FieldTypes.OneToOne; }; +/** Schema representation of a many to many relationship */ export type ManyToManySchema = { + /** Targetted collection */ foreignCollection?: string; + /** Targetted key of the collection */ foreignKey?: string; otherField?: string; throughCollection?: string; @@ -90,7 +108,7 @@ export type ManyToManySchema = { export type ColumnType = PrimitiveTypes | { [key: string]: ColumnType } | [ColumnType]; -/* Enumeration of supported primitive types */ +/** Enumeration of supported primitive types */ export enum PrimitiveTypes { Boolean = "Boolean", Date = "Date", @@ -104,7 +122,7 @@ export enum PrimitiveTypes { Uuid = "Uuid", } -/* Enumeration of supported field types */ +/** Enumeration of supported field types */ export enum FieldTypes { Column = "Column", ManyToOne = "ManyToOne", From 91c7b94aad8ca451501691c18fd9233435d8d659 Mon Sep 17 00:00:00 2001 From: jeffladiray Date: Fri, 17 Dec 2021 10:14:53 +0100 Subject: [PATCH 3/3] docs: more tests --- .../{datasource/index.md => collection.md} | 8 +--- .../datasource-toolkit/docs/datasource.md | 7 +++ packages/datasource-toolkit/src/index.ts | 6 +++ .../src/interfaces/action.ts | 43 +++++++++++++++++++ .../src/interfaces/collection.ts | 3 -- 5 files changed, 57 insertions(+), 10 deletions(-) rename packages/datasource-toolkit/docs/{datasource/index.md => collection.md} (50%) create mode 100644 packages/datasource-toolkit/docs/datasource.md diff --git a/packages/datasource-toolkit/docs/datasource/index.md b/packages/datasource-toolkit/docs/collection.md similarity index 50% rename from packages/datasource-toolkit/docs/datasource/index.md rename to packages/datasource-toolkit/docs/collection.md index 399c37ce35..d9bec89d83 100644 --- a/packages/datasource-toolkit/docs/datasource/index.md +++ b/packages/datasource-toolkit/docs/collection.md @@ -1,10 +1,4 @@ -> **_NOTE:_** Implementing a Collection or a Datasource manually is an advanced notion. If you're just starting with Forest Admin, you should start your project with one of our existing Datasources. - -## Datasource - -### What is a datasource? - -A Datasource represent a list of [Collection](#collection). It is mainly used to aggregate multiples collections from an external source of data. +> **_NOTE:_** Implementing a Collection manually is an advanced notion. If you're just starting with Forest Admin, you should start your project with one of our existing Datasources. ## Collection diff --git a/packages/datasource-toolkit/docs/datasource.md b/packages/datasource-toolkit/docs/datasource.md new file mode 100644 index 0000000000..ce296e02c7 --- /dev/null +++ b/packages/datasource-toolkit/docs/datasource.md @@ -0,0 +1,7 @@ +> **_NOTE:_** Implementing a Collection manually is an advanced notion. If you're just starting with Forest Admin, you should start your project with one of our existing Datasources. + +## Datasource + +### What is a Datasource? + +A Datasource represent a list of [Collection](#collection). It is mainly used to aggregate multiples collections from an external source of data. diff --git a/packages/datasource-toolkit/src/index.ts b/packages/datasource-toolkit/src/index.ts index 9ccc369e61..f194bc813b 100644 --- a/packages/datasource-toolkit/src/index.ts +++ b/packages/datasource-toolkit/src/index.ts @@ -1,3 +1,9 @@ +/** + * [[include:packages/datasource-toolkit/docs/datasource.md]] + * [[include:packages/datasource-toolkit/docs/collection.md]] + * @module Datasource-toolkit + */ + export * from "./interfaces/schema"; export * from "./interfaces/collection"; export * from "./interfaces/action"; diff --git a/packages/datasource-toolkit/src/interfaces/action.ts b/packages/datasource-toolkit/src/interfaces/action.ts index 381a6bd138..55c96fec04 100644 --- a/packages/datasource-toolkit/src/interfaces/action.ts +++ b/packages/datasource-toolkit/src/interfaces/action.ts @@ -1,8 +1,22 @@ import { Projection } from "./query/projection"; import { RecordData } from "./query/record"; +/** + * Interface that Actions should implements + */ export interface Action { + /** + * Function called when an Action is triggered + * @params formValues + * @params selection + */ execute(formValues: RecordData, selection?: Selection): Promise; + /** + * Function called to retrieve an action form + * @params selection + * @params changedField + * @params formValues + */ getForm( selection?: Selection, changedField?: string, @@ -10,10 +24,16 @@ export interface Action { ): Promise; } +/** + * Represent an action form + */ export interface ActionForm { fields: ActionField[]; } +/** + * Represent an action field + */ export interface ActionField { field: string; description?: string; @@ -27,6 +47,7 @@ export interface ActionField { collectionName?: string; // When type === ActionFieldType.Collection } +/** Enumeration of supported action field types */ export enum ActionFieldType { Boolean = "Boolean", Collection = "Collection", @@ -42,6 +63,7 @@ export enum ActionFieldType { StringList = "String[]", } +/** Enumeration of supported action response types */ export enum ActionResponseType { Success, Error, @@ -50,6 +72,11 @@ export enum ActionResponseType { Redirect, } +/** + * Represent a success action response + * + * It will trigger a green/success toastr when calling the action + */ export type SuccessReponse = { type: ActionResponseType.Success; message: string; @@ -59,27 +86,43 @@ export type SuccessReponse = { }; }; +/** + * Represent an error action response + * + * It will trigger a red/danger toastr when calling the action + */ export type ErrorResponse = SuccessReponse & { type: ActionResponseType.Error }; +/** Represent an action response of type webhook */ export type WebHookReponse = { type: ActionResponseType.Webhook; + /** URL of the webhook */ url: string; + /** Method used to call the webhook */ method: "GET" | "POST"; + /** A set of headers to happen to the webhook */ headers: { [key: string]: string }; + /** The body to use when calling the webhook */ body: unknown; }; +/** Represent an action response of type file */ export type FileResponse = { type: ActionResponseType.File; + /** Mime type of the response */ mimeType: string; + /** A stream of the file to respond */ stream: ReadableStream; }; +/** Represent an action response of type redirection */ export type RedirectResponse = { type: ActionResponseType.Redirect; + /** Path to redirect to */ path: string; }; +/** Represent the type of action response */ export type ActionResponse = | SuccessReponse | ErrorResponse diff --git a/packages/datasource-toolkit/src/interfaces/collection.ts b/packages/datasource-toolkit/src/interfaces/collection.ts index 6a13367f5b..00e664fc2b 100644 --- a/packages/datasource-toolkit/src/interfaces/collection.ts +++ b/packages/datasource-toolkit/src/interfaces/collection.ts @@ -1,6 +1,3 @@ -/** - * [[include:packages/datasource-toolkit/docs/datasource/index.md]] - */ import { Action } from "./action"; import { AggregateResult, Aggregation } from "./query/aggregation"; import { Projection } from "./query/projection";