@data-fair/lib-common-types 1.8.4 → 1.9.1

package/catalog/.type/index.d.ts

@@ -0,0 +1,110 @@
+
+export const schemaExports: string[]
+
+// see https://github.com/bcherny/json-schema-to-typescript/issues/439 if some types are not exported
+/**
+ * The list of capabilities that a catalog can have.
+ *  - listDatasets: The catalog can list datasets and get one dataset
+ *  - search: The catalog can use a search param in the listDatasets method
+ *  - pagination: The catalog can paginate the results of the listDatasets method
+ *  - publishDataset: The catalog can publish and delete datasets
+ *
+ * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
+ * via the `definition` "capability".
+ */
+export type Capability = "listDatasets" | "publishDataset" | "search" | "pagination" | "additionalFilters";
+
+export type HttpsGithubComDataFairLibCatalog = {}
+/**
+ * The metadata of the catalog plugin
+ *
+ * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
+ * via the `definition` "metadata".
+ */
+export type Metadata = {
+  /**
+   * The title of the plugin to be displayed in the UI
+   */
+  title: string;
+  /**
+   * The description of the plugin to be displayed in the UI
+   */
+  description: string;
+  /**
+   * The SVG Path icon of the plugin
+   */
+  icon: string;
+  /**
+   * The list of capabilities that a catalog can have.
+   */
+  capabilities: Capability[];
+}
+/**
+ * The normalized dataset format
+ *
+ * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
+ * via the `definition` "catalogDataset".
+ */
+export type CatalogDataset = {
+  id: string;
+  title: string;
+  description?: string;
+  keywords?: string[];
+  origin?: string;
+  image?: string;
+  license?: string;
+  frequency?: string;
+  private?: boolean;
+  resources?: CatalogResourceDataset;
+}
+/**
+ * The normalized resource format
+ *
+ * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
+ * via the `definition` "catalogResourceDataset".
+ */
+export type CatalogResourceDataset = {
+  id: string;
+  title: string;
+  format: string;
+  url: string;
+  fileName?: string;
+  mimeType?: string;
+  size?: number;
+}
+/**
+ * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
+ * via the `definition` "publication".
+ */
+export type Publication = {
+  /**
+   * Id of this publication, for a better search in database
+   */
+  publicationId?: string;
+  /**
+   * Id of the catalog where the resource is published
+   */
+  catalogId: string;
+  /**
+   * Id of the dataset in the remote catalog
+   */
+  remoteDatasetId?: string;
+  /**
+   * Id of the resource in the dataset in the remote catalog, used if a DataFair dataset is published as a resource in a remote catalog
+   */
+  remoteResourceId?: string;
+  /**
+   * True if the publication is a resource, false or undefined if it is a dataset
+   */
+  isResource?: boolean;
+  /**
+   * A simple flag to clearly identify the publications that were successful. If "error" then the error key should be defined.
+   */
+  status: "waiting" | "published" | "error" | "deleted";
+  /**
+   * Date of the last update for this publication
+   */
+  publishedAt?: string;
+  error?: string;
+}
+

package/catalog/.type/index.js

@@ -0,0 +1,7 @@
+/* eslint-disable */
+
+
+
+export const schemaExports = [
+  "types"
+]

package/catalog/index.d.ts

@@ -0,0 +1,66 @@
+import type { Capability, Metadata, CatalogDataset, Publication } from './.type/index.js';
+export type { CatalogDataset } from './.type/index.js';
+export type { CatalogResourceDataset } from './.type/index.js';
+export type { Publication } from './.type/index.js';
+/** Utility type to check if a type T includes a type U */
+type Includes<T extends any[], U> = U extends T[number] ? true : false;
+/**
+ * Generic catalog plugin interface.
+ * @template TCatalogConfig - The type of the catalog configuration.
+ * @template TCapabilities - The capabilities of the catalog.
+ */
+export type CatalogPlugin<TCatalogConfig = any, TCapabilities extends Capability[] = any> = BaseCatalogPlugin<TCatalogConfig, TCapabilities> & (Includes<TCapabilities, 'listDatasets'> extends true ? WithListDatasets<TCatalogConfig, TCapabilities> : {}) & (Includes<TCapabilities, 'publishDataset'> extends true ? WithPublishDataset<TCatalogConfig> : {});
+type BaseCatalogPlugin<TCatalogConfig, TCapabilities extends Capability[]> = {
+    metadata: CatalogMetadata<TCapabilities>;
+    configSchema: TCatalogConfig;
+    /** Function to validates the catalog configuration. */
+    assertConfigValid(catalogConfig: any): asserts catalogConfig is TCatalogConfig;
+};
+type WithListDatasets<TCatalogConfig, TCapabilities extends Capability[]> = {
+    /** List available datasets in the catalog. */
+    listDatasets: (catalogConfig: TCatalogConfig, params: ListDatasetsParams<TCapabilities>) => Promise<{
+        count: number;
+        results: CatalogDataset[];
+    }>;
+    /** Get a specific dataset. */
+    getDataset: (catalogConfig: TCatalogConfig, datasetId: string) => Promise<CatalogDataset | undefined>;
+} & (Includes<TCapabilities, 'additionalFilters'> extends true ? {
+    filtersSchema: Record<string, any>;
+} : {});
+type WithPublishDataset<TCatalogConfig> = {
+    /**
+     * Publish/Update a dataset or add/update a resource to a dataset
+     * @param catalogConfig The configuration of the catalog
+     * @param dataset The datafair dataset to publish
+     * @param publication The publication in the datafair dataset to process
+     * @returns A promise that resolves to the updated publication object with the publicationId, the remoteDatasetId and the status after the dataset is published
+     */
+    publishDataset: (catalogConfig: TCatalogConfig, dataset: any, publication: Publication) => Promise<Publication>;
+    /**
+     * Delete a dataset or remove a resource from a dataset
+     * @param catalogConfig The configuration of the catalog
+     * @param datasetId The id of the remoteDataset to delete, or the dataset where the resource to delete is
+     * @param resourceId The id of the resource to delete
+     */
+    deleteDataset: (catalogConfig: TCatalogConfig, datasetId: string, resourceId?: string) => Promise<void>;
+};
+/**
+ * The parameters for the listDatasets method.
+ * - search capability : take param q
+ * - pagination capability : take params page and size
+ */
+type ListDatasetsParams<TCapabilities extends Capability[]> = (Includes<TCapabilities, 'search'> extends true ? SearchParams : {}) & (Includes<TCapabilities, 'pagination'> extends true ? PaginationParams : {}) & (Includes<TCapabilities, 'additionalFilters'> extends true ? Record<string, string> : {});
+type SearchParams = {
+    q?: string;
+};
+type PaginationParams = {
+    page?: number;
+    size?: number;
+};
+/**
+ * The metadata of the catalog plugin.
+ * @template TCapabilities - This ensures that the `capabilities` field in the metadata is of the same type as `TCapabilities`.
+ */
+export type CatalogMetadata<TCapabilities extends Capability[]> = Metadata & {
+    capabilities: TCapabilities;
+};

package/catalog/index.js

@@ -0,0 +1 @@
+export {}

package/catalog/schema.d.ts

@@ -0,0 +1,151 @@
+declare const _default: {
+    $id: string;
+    'x-exports': string[];
+    type: string;
+    additionalProperties: boolean;
+    $defs: {
+        capability: {
+            type: string;
+            description: string;
+            enum: string[];
+        };
+        metadata: {
+            type: string;
+            description: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                title: {
+                    description: string;
+                    type: string;
+                };
+                description: {
+                    description: string;
+                    type: string;
+                };
+                icon: {
+                    description: string;
+                    type: string;
+                };
+                capabilities: {
+                    description: string;
+                    type: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+            };
+        };
+        catalogDataset: {
+            type: string;
+            description: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                id: {
+                    type: string;
+                };
+                title: {
+                    type: string;
+                };
+                description: {
+                    type: string;
+                };
+                keywords: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                origin: {
+                    type: string;
+                };
+                image: {
+                    type: string;
+                };
+                license: {
+                    type: string;
+                };
+                frequency: {
+                    type: string;
+                };
+                private: {
+                    type: string;
+                };
+                resources: {
+                    $ref: string;
+                };
+            };
+        };
+        catalogResourceDataset: {
+            type: string;
+            description: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                id: {
+                    type: string;
+                };
+                title: {
+                    type: string;
+                };
+                format: {
+                    type: string;
+                };
+                url: {
+                    type: string;
+                };
+                fileName: {
+                    type: string;
+                };
+                mimeType: {
+                    type: string;
+                };
+                size: {
+                    type: string;
+                };
+            };
+        };
+        publication: {
+            type: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                publicationId: {
+                    type: string;
+                    description: string;
+                };
+                catalogId: {
+                    type: string;
+                    description: string;
+                };
+                remoteDatasetId: {
+                    type: string;
+                    description: string;
+                };
+                remoteResourceId: {
+                    type: string;
+                    description: string;
+                };
+                isResource: {
+                    type: string;
+                    description: string;
+                };
+                status: {
+                    type: string;
+                    description: string;
+                    enum: string[];
+                };
+                publishedAt: {
+                    type: string;
+                    description: string;
+                    format: string;
+                };
+                error: {
+                    type: string;
+                };
+            };
+        };
+    };
+};
+export default _default;

package/catalog/schema.js

@@ -0,0 +1,160 @@
+export default {
+  $id: 'https://github.com/data-fair/lib/catalog',
+  'x-exports': ['types'],
+  type: 'object',
+  additionalProperties: false,
+  $defs: {
+    capability: {
+      type: 'string',
+      description: `The list of capabilities that a catalog can have.
+ - listDatasets: The catalog can list datasets and get one dataset
+ - search: The catalog can use a search param in the listDatasets method
+ - pagination: The catalog can paginate the results of the listDatasets method
+ - publishDataset: The catalog can publish and delete datasets`,
+      enum: [
+        'listDatasets',
+        'publishDataset',
+        'search',
+        'pagination',
+        'additionalFilters'
+      ]
+    },
+    metadata: {
+      type: 'object',
+      description: 'The metadata of the catalog plugin',
+      required: ['title', 'description', 'icon', 'capabilities'],
+      additionalProperties: false,
+      properties: {
+        title: {
+          description: 'The title of the plugin to be displayed in the UI',
+          type: 'string'
+        },
+        description: {
+          description: 'The description of the plugin to be displayed in the UI',
+          type: 'string'
+        },
+        icon: {
+          description: 'The SVG Path icon of the plugin',
+          type: 'string'
+        },
+        capabilities: {
+          description: 'The list of capabilities that a catalog can have.',
+          type: 'array',
+          items: {
+            $ref: '#/$defs/capability'
+          }
+        }
+      }
+    },
+    catalogDataset: {
+      type: 'object',
+      description: 'The normalized dataset format',
+      required: ['id', 'title'],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: 'string'
+        },
+        title: {
+          type: 'string'
+        },
+        description: {
+          type: 'string'
+        },
+        keywords: {
+          type: 'array',
+          items: {
+            type: 'string'
+          }
+        },
+        origin: {
+          type: 'string'
+        },
+        image: {
+          type: 'string'
+        },
+        license: {
+          type: 'string'
+        },
+        frequency: {
+          type: 'string'
+        },
+        private: {
+          type: 'boolean'
+        },
+        resources: {
+          $ref: '#/$defs/catalogResourceDataset'
+        },
+      },
+    },
+    catalogResourceDataset: {
+      type: 'object',
+      description: 'The normalized resource format',
+      required: ['id', 'title', 'format', 'url'],
+      additionalProperties: false,
+      properties: {
+        id: {
+          type: 'string'
+        },
+        title: {
+          type: 'string'
+        },
+        format: {
+          type: 'string'
+        },
+        url: {
+          type: 'string'
+        },
+        fileName: {
+          type: 'string'
+        },
+        mimeType: {
+          type: 'string'
+        },
+        size: {
+          type: 'number'
+        }
+      }
+    },
+    publication: {
+      type: 'object',
+      required: ['catalogId', 'status'],
+      additionalProperties: false,
+      properties: {
+        publicationId: {
+          type: 'string',
+          description: 'Id of this publication, for a better search in database'
+        },
+        catalogId: {
+          type: 'string',
+          description: 'Id of the catalog where the resource is published'
+        },
+        remoteDatasetId: {
+          type: 'string',
+          description: 'Id of the dataset in the remote catalog'
+        },
+        remoteResourceId: {
+          type: 'string',
+          description: 'Id of the resource in the dataset in the remote catalog, used if a DataFair dataset is published as a resource in a remote catalog'
+        },
+        isResource: {
+          type: 'boolean',
+          description: 'True if the publication is a resource, false or undefined if it is a dataset '
+        },
+        status: {
+          type: 'string',
+          description: 'A simple flag to clearly identify the publications that were successful. If "error" then the error key should be defined.',
+          enum: ['waiting', 'published', 'error', 'deleted']
+        },
+        publishedAt: {
+          type: 'string',
+          description: 'Date of the last update for this publication',
+          format: 'date-time'
+        },
+        error: {
+          type: 'string'
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@data-fair/lib-common-types",
-  "version": "1.8.4",
+  "version": "1.9.1",
   "description": "Shared schemas and built type definitions in the data-fair stack.",
   "main": "index.js",
   "scripts": {