@data-fair/lib-common-types 1.10.4 → 1.10.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,21 +4,31 @@ export const schemaExports: string[]
4
4
  // see https://github.com/bcherny/json-schema-to-typescript/issues/439 if some types are not exported
5
5
  /**
6
6
  * The list of capabilities that a catalog can have.
7
- * - listDatasets: The catalog can list datasets and get one dataset
8
- * - search: The catalog can use a search param in the listDatasets method
9
- * - pagination: The catalog can paginate the results of the listDatasets method
10
- * - publishDataset: The catalog can publish and delete datasets
7
+ * - import: The plugin can list some resources organized in folders and import them
8
+ * - search: The plugin can use a search param in the listResources method
9
+ * - pagination: The plugin can paginate the results of the listResources method
10
+ * - additionalFilters: The plugin can use additional filters in the listResources method
11
+ * - importConfig: The plugin gives an import configuration schema
12
+ * - publishDataset: The plugin can publish a dataset
13
+ * - deletePublication: The plugin can delete a dataset or a resource published in a remote catalog
11
14
  *
12
- * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
15
+ * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
13
16
  * via the `definition` "capability".
14
17
  */
15
- export type Capability = "listDatasets" | "publishDataset" | "search" | "pagination" | "additionalFilters";
18
+ export type Capability =
19
+ | "import"
20
+ | "search"
21
+ | "pagination"
22
+ | "additionalFilters"
23
+ | "importConfig"
24
+ | "publishDataset"
25
+ | "deletePublication";
16
26
 
17
- export type HttpsGithubComDataFairLibCatalog = {}
27
+ export type CatalogsCommonTypes = {}
18
28
  /**
19
29
  * The metadata of the catalog plugin
20
30
  *
21
- * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
31
+ * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
22
32
  * via the `definition` "metadata".
23
33
  */
24
34
  export type Metadata = {
@@ -36,71 +46,75 @@ export type Metadata = {
36
46
  capabilities: Capability[];
37
47
  }
38
48
  /**
39
- * The normalized dataset format
40
- *
41
- * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
42
- * via the `definition` "catalogDataset".
49
+ * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
50
+ * via the `definition` "folder".
43
51
  */
44
- export type CatalogDataset = {
52
+ export type Folder = {
45
53
  id: string;
46
54
  title: string;
47
- description?: string;
48
- keywords?: string[];
49
- origin?: string;
50
- image?: string;
51
- license?: string;
52
- frequency?: string;
53
- private?: boolean;
54
- resources?: CatalogResourceDataset[];
55
+ type: "folder";
55
56
  }
56
57
  /**
57
- * The normalized resource format
58
+ * The normalized resource to import from a remote catalog to Data Fair
58
59
  *
59
- * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
60
- * via the `definition` "catalogResourceDataset".
60
+ * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
61
+ * via the `definition` "resource".
61
62
  */
62
- export type CatalogResourceDataset = {
63
+ export type Resource = {
64
+ /**
65
+ * The unique identifier of the resource, independent of the folder it is in
66
+ */
63
67
  id: string;
64
68
  title: string;
69
+ type: "resource";
70
+ description?: string;
65
71
  format: string;
66
72
  url: string;
67
73
  fileName?: string;
68
74
  mimeType?: string;
69
75
  size?: number;
76
+ keywords?: string[];
77
+ image?: string;
78
+ license?: string;
79
+ frequency?: string;
80
+ private?: boolean;
70
81
  }
71
82
  /**
72
- * This interface was referenced by `HttpsGithubComDataFairLibCatalog`'s JSON-Schema
83
+ * A small object that contains the information needed to publish or update a dataset or a resource
84
+ *
85
+ * This interface was referenced by `CatalogsCommonTypes`'s JSON-Schema
73
86
  * via the `definition` "publication".
74
87
  */
75
88
  export type Publication = {
76
89
  /**
77
- * Id of this publication, for a better search in database
90
+ * The URL of the publication site where the user will be redirected from the remote catalog
78
91
  */
79
- publicationId?: string;
92
+ publicationSite?: string;
80
93
  /**
81
- * Id of the catalog where the resource is published
94
+ * Dataset from the remote catalog, used if a local dataset is published as a dataset on a remote catalog. If it is defined during publication, then the remote dataset must be updated.
82
95
  */
83
- catalogId: string;
96
+ remoteDataset?: {
97
+ id: string;
98
+ title?: string;
99
+ /**
100
+ * URL to view the dataset in the remote catalog
101
+ */
102
+ url?: string;
103
+ };
84
104
  /**
85
- * Id of the dataset in the remote catalog
105
+ * Dataset's resource from the remote catalog, used if a local dataset is published as a resource on a remote catalog. If it is defined during publication, then the remote resource must be updated.
86
106
  */
87
- remoteDatasetId?: string;
107
+ remoteResource?: {
108
+ id: string;
109
+ title?: string;
110
+ /**
111
+ * URL to view the resource in the remote catalog
112
+ */
113
+ url?: string;
114
+ };
88
115
  /**
89
- * 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
90
- */
91
- remoteResourceId?: string;
92
- /**
93
- * True if the publication is a resource, false or undefined if it is a dataset
116
+ * If true, the publication is for a resource, otherwise it is for a dataset
94
117
  */
95
118
  isResource?: boolean;
96
- /**
97
- * A simple flag to clearly identify the publications that were successful. If "error" then the error key should be defined.
98
- */
99
- status: "waiting" | "published" | "error" | "deleted";
100
- /**
101
- * Date of the last update for this publication
102
- */
103
- publishedAt?: string;
104
- error?: string;
105
119
  }
106
120
 
@@ -1,4 +1,4 @@
1
- import type { Capability, Metadata, CatalogDataset, Publication } from './.type/index.js';
1
+ import type { Capability, Folder, Metadata, Publication, Resource } from './.type/index.js';
2
2
  export * from './.type/index.js';
3
3
  /** Utility type to check if a type T includes a type U */
4
4
  type Includes<T extends any[], U> = U extends T[number] ? true : false;
@@ -7,33 +7,50 @@ type Includes<T extends any[], U> = U extends T[number] ? true : false;
7
7
  * @template TCatalogConfig - The type of the catalog configuration.
8
8
  * @template TCapabilities - The capabilities of the catalog.
9
9
  */
10
- 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> : {});
10
+ export type CatalogPlugin<TCatalogConfig = object, TCapabilities extends Capability[] = Capability[]> = BaseCatalogPlugin<TCatalogConfig, TCapabilities> & (Includes<TCapabilities, 'import'> extends true ? WithImport<TCatalogConfig, TCapabilities> : {}) & (Includes<TCapabilities, 'publishDataset'> extends true ? WithPublishDataset<TCatalogConfig> : {}) & (Includes<TCapabilities, 'deletePublication'> extends true ? WithDeletePublication<TCatalogConfig> : {});
11
11
  type BaseCatalogPlugin<TCatalogConfig, TCapabilities extends Capability[]> = {
12
12
  metadata: CatalogMetadata<TCapabilities>;
13
13
  configSchema: TCatalogConfig;
14
14
  /** Function to validates the catalog configuration. */
15
15
  assertConfigValid(catalogConfig: any): asserts catalogConfig is TCatalogConfig;
16
16
  };
17
- type WithListDatasets<TCatalogConfig, TCapabilities extends Capability[]> = {
18
- /** List available datasets in the catalog. */
19
- listDatasets: (catalogConfig: TCatalogConfig, params: ListDatasetsParams<TCapabilities>) => Promise<{
17
+ /**
18
+ * Type for catalog implementations that support listing and retrieving resources.
19
+ * Resources are organized within folders in the catalog structure.
20
+ *
21
+ * @template TCatalogConfig - Configuration type for the catalog
22
+ * @template TCapabilities - Array of capability types that the catalog supports
23
+ */
24
+ type WithImport<TCatalogConfig, TCapabilities extends Capability[]> = {
25
+ /** List available folders and resources in the catalog. */
26
+ list: (context: ListContext<TCatalogConfig, TCapabilities>) => Promise<{
20
27
  count: number;
21
- results: CatalogDataset[];
28
+ results: (Folder | Resource)[];
29
+ path: Folder[];
22
30
  }>;
23
- /** Get a specific dataset. */
24
- getDataset: (catalogConfig: TCatalogConfig, datasetId: string) => Promise<CatalogDataset | undefined>;
31
+ /** Get informations about a specific resource. */
32
+ getResource: (catalogConfig: TCatalogConfig, resourceId: string) => Promise<Resource | undefined>;
33
+ /**
34
+ * Download the resource to a temporary file from a context
35
+ * @returns The path to the downloaded resource file, or undefined if the download failed
36
+ */
37
+ downloadResource: (context: DownloadResourceContext<TCatalogConfig>) => Promise<string | undefined>;
25
38
  } & (Includes<TCapabilities, 'additionalFilters'> extends true ? {
26
39
  filtersSchema: Record<string, any>;
40
+ } : {}) & (Includes<TCapabilities, 'importConfig'> extends true ? {
41
+ importConfigSchema: Record<string, any>;
27
42
  } : {});
28
43
  type WithPublishDataset<TCatalogConfig> = {
29
44
  /**
30
45
  * Publish/Update a dataset or add/update a resource to a dataset
31
46
  * @param catalogConfig The configuration of the catalog
32
47
  * @param dataset The datafair dataset to publish
33
- * @param publication The publication in the datafair dataset to process
34
- * @returns A promise that resolves to the updated publication object with the publicationId, the remoteDatasetId and the status after the dataset is published
48
+ * @param publication The publication to process
49
+ * @returns A promise that is resolved when the dataset is published
35
50
  */
36
- publishDataset: (catalogConfig: TCatalogConfig, dataset: any, publication: Publication) => Promise<Publication>;
51
+ publishDataset: (catalogConfig: TCatalogConfig, dataset: object, publication: Publication) => Promise<Publication>;
52
+ };
53
+ type WithDeletePublication<TCatalogConfig> = {
37
54
  /**
38
55
  * Delete a dataset or remove a resource from a dataset
39
56
  * @param catalogConfig The configuration of the catalog
@@ -42,12 +59,16 @@ type WithPublishDataset<TCatalogConfig> = {
42
59
  */
43
60
  deleteDataset: (catalogConfig: TCatalogConfig, datasetId: string, resourceId?: string) => Promise<void>;
44
61
  };
45
- /**
46
- * The parameters for the listDatasets method.
47
- * - search capability : take param q
48
- * - pagination capability : take params page and size
49
- */
50
- 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> : {});
62
+ export type ListContext<TCatalogConfig, TCapabilities extends Capability[]> = {
63
+ /** The catalog configuration */
64
+ catalogConfig: TCatalogConfig;
65
+ /** The specific import configuration, if applicable */
66
+ params: ListParams<TCapabilities>;
67
+ };
68
+ type ListParams<TCapabilities extends Capability[]> = {
69
+ /** The current level folder is used to list subfolders and resources. */
70
+ currentFolderId?: string;
71
+ } & (Includes<TCapabilities, 'search'> extends true ? SearchParams : {}) & (Includes<TCapabilities, 'pagination'> extends true ? PaginationParams : {}) & (Includes<TCapabilities, 'additionalFilters'> extends true ? Record<string, string> : {});
51
72
  type SearchParams = {
52
73
  q?: string;
53
74
  };
@@ -55,6 +76,16 @@ type PaginationParams = {
55
76
  page?: number;
56
77
  size?: number;
57
78
  };
79
+ export type DownloadResourceContext<TCatalogConfig> = {
80
+ /** The catalog configuration */
81
+ catalogConfig: TCatalogConfig;
82
+ /** The specific import configuration, if applicable */
83
+ importConfig: Record<string, any>;
84
+ /** The ID of the remote resource to download */
85
+ resourceId: string;
86
+ /** The path to the working directory */
87
+ tmpDir: string;
88
+ };
58
89
  /**
59
90
  * The metadata of the catalog plugin.
60
91
  * @template TCapabilities - This ensures that the `capabilities` field in the metadata is of the same type as `TCapabilities`.
@@ -2,6 +2,7 @@ declare const _default: {
2
2
  $id: string;
3
3
  'x-exports': string[];
4
4
  type: string;
5
+ title: string;
5
6
  additionalProperties: boolean;
6
7
  $defs: {
7
8
  capability: {
@@ -32,9 +33,8 @@ declare const _default: {
32
33
  };
33
34
  };
34
35
  };
35
- catalogDataset: {
36
+ folder: {
36
37
  type: string;
37
- description: string;
38
38
  required: string[];
39
39
  additionalProperties: boolean;
40
40
  properties: {
@@ -44,39 +44,12 @@ declare const _default: {
44
44
  title: {
45
45
  type: string;
46
46
  };
47
- description: {
48
- type: string;
49
- };
50
- keywords: {
51
- type: string;
52
- items: {
53
- type: string;
54
- };
55
- };
56
- origin: {
57
- type: string;
58
- };
59
- image: {
60
- type: string;
61
- };
62
- license: {
63
- type: string;
64
- };
65
- frequency: {
66
- type: string;
67
- };
68
- private: {
69
- type: string;
70
- };
71
- resources: {
72
- type: string;
73
- items: {
74
- $ref: string;
75
- };
47
+ type: {
48
+ const: string;
76
49
  };
77
50
  };
78
51
  };
79
- catalogResourceDataset: {
52
+ resource: {
80
53
  type: string;
81
54
  description: string;
82
55
  required: string[];
@@ -84,10 +57,17 @@ declare const _default: {
84
57
  properties: {
85
58
  id: {
86
59
  type: string;
60
+ description: string;
87
61
  };
88
62
  title: {
89
63
  type: string;
90
64
  };
65
+ type: {
66
+ const: string;
67
+ };
68
+ description: {
69
+ type: string;
70
+ };
91
71
  format: {
92
72
  type: string;
93
73
  };
@@ -103,45 +83,74 @@ declare const _default: {
103
83
  size: {
104
84
  type: string;
105
85
  };
106
- };
107
- };
108
- publication: {
109
- type: string;
110
- required: string[];
111
- additionalProperties: boolean;
112
- properties: {
113
- publicationId: {
86
+ keywords: {
114
87
  type: string;
115
- description: string;
88
+ items: {
89
+ type: string;
90
+ };
116
91
  };
117
- catalogId: {
92
+ image: {
118
93
  type: string;
119
- description: string;
120
94
  };
121
- remoteDatasetId: {
95
+ license: {
122
96
  type: string;
123
- description: string;
124
97
  };
125
- remoteResourceId: {
98
+ frequency: {
126
99
  type: string;
127
- description: string;
128
100
  };
129
- isResource: {
101
+ private: {
102
+ type: string;
103
+ };
104
+ };
105
+ };
106
+ publication: {
107
+ type: string;
108
+ additionalProperties: boolean;
109
+ description: string;
110
+ properties: {
111
+ publicationSite: {
130
112
  type: string;
131
113
  description: string;
132
114
  };
133
- status: {
115
+ remoteDataset: {
134
116
  type: string;
117
+ required: string[];
118
+ additionalProperties: boolean;
135
119
  description: string;
136
- enum: string[];
120
+ properties: {
121
+ id: {
122
+ type: string;
123
+ };
124
+ title: {
125
+ type: string;
126
+ };
127
+ url: {
128
+ type: string;
129
+ description: string;
130
+ };
131
+ };
137
132
  };
138
- publishedAt: {
133
+ remoteResource: {
139
134
  type: string;
135
+ required: string[];
136
+ additionalProperties: boolean;
140
137
  description: string;
141
- format: string;
138
+ properties: {
139
+ id: {
140
+ type: string;
141
+ };
142
+ title: {
143
+ type: string;
144
+ };
145
+ url: {
146
+ type: string;
147
+ description: string;
148
+ };
149
+ };
142
150
  };
143
- error: {
151
+ isResource: {
144
152
  type: string;
153
+ description: string;
145
154
  };
146
155
  };
147
156
  };
package/catalog/schema.js CHANGED
@@ -2,21 +2,27 @@ export default {
2
2
  $id: 'https://github.com/data-fair/lib/catalog',
3
3
  'x-exports': ['types'],
4
4
  type: 'object',
5
+ title: 'Catalogs common types',
5
6
  additionalProperties: false,
6
7
  $defs: {
7
8
  capability: {
8
9
  type: 'string',
9
10
  description: `The list of capabilities that a catalog can have.
10
- - listDatasets: The catalog can list datasets and get one dataset
11
- - search: The catalog can use a search param in the listDatasets method
12
- - pagination: The catalog can paginate the results of the listDatasets method
13
- - publishDataset: The catalog can publish and delete datasets`,
11
+ - import: The plugin can list some resources organized in folders and import them
12
+ - search: The plugin can use a search param in the listResources method
13
+ - pagination: The plugin can paginate the results of the listResources method
14
+ - additionalFilters: The plugin can use additional filters in the listResources method
15
+ - importConfig: The plugin gives an import configuration schema
16
+ - publishDataset: The plugin can publish a dataset
17
+ - deletePublication: The plugin can delete a dataset or a resource published in a remote catalog`,
14
18
  enum: [
15
- 'listDatasets',
16
- 'publishDataset',
19
+ 'import',
17
20
  'search',
18
21
  'pagination',
19
- 'additionalFilters'
22
+ 'additionalFilters',
23
+ 'importConfig',
24
+ 'publishDataset',
25
+ 'deletePublication'
20
26
  ]
21
27
  },
22
28
  metadata: {
@@ -42,10 +48,9 @@ export default {
42
48
  }
43
49
  }
44
50
  },
45
- catalogDataset: {
51
+ folder: {
46
52
  type: 'object',
47
- description: 'The normalized dataset format',
48
- required: ['id', 'title'],
53
+ required: ['id', 'title', 'type'],
49
54
  additionalProperties: false,
50
55
  properties: {
51
56
  id: {
@@ -54,50 +59,30 @@ export default {
54
59
  title: {
55
60
  type: 'string'
56
61
  },
57
- description: {
58
- type: 'string'
59
- },
60
- keywords: {
61
- type: 'array',
62
- items: {
63
- type: 'string'
64
- }
65
- },
66
- origin: {
67
- type: 'string'
68
- },
69
- image: {
70
- type: 'string'
71
- },
72
- license: {
73
- type: 'string'
74
- },
75
- frequency: {
76
- type: 'string'
77
- },
78
- private: {
79
- type: 'boolean'
80
- },
81
- resources: {
82
- type: 'array',
83
- items: {
84
- $ref: '#/$defs/catalogResourceDataset'
85
- }
62
+ type: {
63
+ const: 'folder',
86
64
  }
87
65
  },
88
66
  },
89
- catalogResourceDataset: {
67
+ resource: {
90
68
  type: 'object',
91
- description: 'The normalized resource format',
92
- required: ['id', 'title', 'format', 'url'],
69
+ description: 'The normalized resource to import from a remote catalog to Data Fair',
70
+ required: ['id', 'title', 'type', 'format', 'url'],
93
71
  additionalProperties: false,
94
72
  properties: {
95
73
  id: {
96
- type: 'string'
74
+ type: 'string',
75
+ description: 'The unique identifier of the resource, independent of the folder it is in'
97
76
  },
98
77
  title: {
99
78
  type: 'string'
100
79
  },
80
+ type: {
81
+ const: 'resource',
82
+ },
83
+ description: {
84
+ type: 'string',
85
+ },
101
86
  format: {
102
87
  type: 'string'
103
88
  },
@@ -112,46 +97,75 @@ export default {
112
97
  },
113
98
  size: {
114
99
  type: 'number'
100
+ },
101
+ keywords: {
102
+ type: 'array',
103
+ items: {
104
+ type: 'string'
105
+ }
106
+ },
107
+ image: {
108
+ type: 'string'
109
+ },
110
+ license: {
111
+ type: 'string'
112
+ },
113
+ frequency: {
114
+ type: 'string'
115
+ },
116
+ private: {
117
+ type: 'boolean'
115
118
  }
116
119
  }
117
120
  },
118
121
  publication: {
119
122
  type: 'object',
120
- required: ['catalogId', 'status'],
121
123
  additionalProperties: false,
124
+ description: 'A small object that contains the information needed to publish or update a dataset or a resource',
122
125
  properties: {
123
- publicationId: {
124
- type: 'string',
125
- description: 'Id of this publication, for a better search in database'
126
- },
127
- catalogId: {
128
- type: 'string',
129
- description: 'Id of the catalog where the resource is published'
130
- },
131
- remoteDatasetId: {
126
+ publicationSite: {
132
127
  type: 'string',
133
- description: 'Id of the dataset in the remote catalog'
128
+ description: 'The URL of the publication site where the user will be redirected from the remote catalog'
129
+ },
130
+ remoteDataset: {
131
+ type: 'object',
132
+ required: ['id'],
133
+ additionalProperties: false,
134
+ description: 'Dataset from the remote catalog, used if a local dataset is published as a dataset on a remote catalog. If it is defined during publication, then the remote dataset must be updated.',
135
+ properties: {
136
+ id: {
137
+ type: 'string',
138
+ },
139
+ title: {
140
+ type: 'string',
141
+ },
142
+ url: {
143
+ type: 'string',
144
+ description: 'URL to view the dataset in the remote catalog'
145
+ }
146
+ }
134
147
  },
135
- remoteResourceId: {
136
- type: 'string',
137
- 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'
148
+ remoteResource: {
149
+ type: 'object',
150
+ required: ['id'],
151
+ additionalProperties: false,
152
+ description: 'Dataset\'s resource from the remote catalog, used if a local dataset is published as a resource on a remote catalog. If it is defined during publication, then the remote resource must be updated.',
153
+ properties: {
154
+ id: {
155
+ type: 'string',
156
+ },
157
+ title: {
158
+ type: 'string',
159
+ },
160
+ url: {
161
+ type: 'string',
162
+ description: 'URL to view the resource in the remote catalog'
163
+ }
164
+ }
138
165
  },
139
166
  isResource: {
140
167
  type: 'boolean',
141
- description: 'True if the publication is a resource, false or undefined if it is a dataset '
142
- },
143
- status: {
144
- type: 'string',
145
- description: 'A simple flag to clearly identify the publications that were successful. If "error" then the error key should be defined.',
146
- enum: ['waiting', 'published', 'error', 'deleted']
147
- },
148
- publishedAt: {
149
- type: 'string',
150
- description: 'Date of the last update for this publication',
151
- format: 'date-time'
152
- },
153
- error: {
154
- type: 'string'
168
+ description: 'If true, the publication is for a resource, otherwise it is for a dataset'
155
169
  }
156
170
  }
157
171
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@data-fair/lib-common-types",
3
- "version": "1.10.4",
3
+ "version": "1.10.6",
4
4
  "description": "Shared schemas and built type definitions in the data-fair stack.",
5
5
  "main": "index.js",
6
6
  "scripts": {