@static-suite/static-suite-data-server 0.0.21 → 0.0.23

package/README.md

@@ -8,6 +8,55 @@ A flexible, fast and developer friendly Data Server for [Static Suite](https://w
 
 Data Server supports static JSON includes (`entityInclude`, `configInclude`, `localeInclude` and `customInclude`) and the dynamic `queryInclude`, keeping track of the relationships between includes and data: when a file changes, it knows which other files should also change, thus enabling _incremental builds_ for any kind of SSG (Gatsby, Next.js, etc).
 
+- [Static Suite Data Server](#static-suite-data-server)
+  - [Options](#options)
+  - [Options from file.](#options-from-file)
+  - [Usage](#usage)
+    - [SSG develop/build phase](#ssg-developbuild-phase)
+    - [Previewing a content from Drupal](#previewing-a-content-from-drupal)
+    - [Developing/debugging queries on a local environment](#developingdebugging-queries-on-a-local-environment)
+  - [Data structure](#data-structure)
+    - [Store internal structure](#store-internal-structure)
+    - [Getting a file](#getting-a-file)
+    - [Getting a subset of files](#getting-a-subset-of-files)
+      - [Subset options](#subset-options)
+      - [Return value](#return-value)
+    - [Getting a subset of files via HTTP](#getting-a-subset-of-files-via-http)
+      - [Return value](#return-value-1)
+    - [Indexes](#indexes)
+      - [Custom indexes](#custom-indexes)
+  - [Queries](#queries)
+  - [Hooks](#hooks)
+    - [Available hooks](#available-hooks)
+      - [`onModuleLoad({config, store, logger }): void`](#onmoduleloadconfig-store-logger--void)
+      - [`onStoreLoadStart({ store, logger, dependencyTagger }): void`](#onstoreloadstart-store-logger-dependencytagger--void)
+      - [`onProcessFile({ store, logger, dependencyTagger, relativeFilepath, fileContent }): fileContent`](#onprocessfile-store-logger-dependencytagger-relativefilepath-filecontent--filecontent)
+      - [`onStoreItemAdd({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitemadd-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreLoadDone({ store, logger, dependencyTagger }): void`](#onstoreloaddone-store-logger-dependencytagger--void)
+      - [`onStoreChangeStart({ store, logger, dependencyTagger, changedFiles }): void`](#onstorechangestart-store-logger-dependencytagger-changedfiles--void)
+      - [`onStoreItemBeforeUpdate({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitembeforeupdate-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreItemAfterUpdate({ store, logger, dependencyTagger, relativeFilepath, storeItem, previousStoreItem }): void`](#onstoreitemafterupdate-store-logger-dependencytagger-relativefilepath-storeitem-previousstoreitem--void)
+      - [`onStoreItemDelete({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitemdelete-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreChangeDone({ store, logger, dependencyTagger, changedFiles }): void`](#onstorechangedone-store-logger-dependencytagger-changedfiles--void)
+      - [`onDumpCreate(options: OnDumpHookOptions): Dump`](#ondumpcreateoptions-ondumphookoptions-dump)
+    - [Hook example](#hook-example)
+      - [`File taxonomy.hook.js`](#file-taxonomyhookjs)
+      - [`File listContentsByTermId.query.js`](#file-listcontentsbytermidqueryjs)
+  - [Tasks](#tasks)
+  - [Dumps](#dumps)
+  - [Dependency tags](#dependency-tags)
+    - [Dependency tagger](#dependency-tagger)
+      - [`setDependency(tag: string, dependsOnTags: string[]): void`](#setdependencytag-string-dependsontags-string-void)
+      - [`addDependency(tag: string, dependsOnTags: string[]): void`](#adddependencytag-string-dependsontags-string-void)
+      - [`deleteDependency(tag: string, dependsOnTags?: string[]): void`](#deletedependencytag-string-dependsontags-string-void)
+      - [`invalidateTags(tags: string[]): void`](#invalidatetagstags-string-void)
+    - [Dependency tags example](#dependency-tags-example)
+      - [`File taxonomy.hook.js`](#file-taxonomyhookjs-1)
+      - [`File listContentsByTermId.query.js`](#file-listcontentsbytermidqueryjs-1)
+  - [Run modes](#run-modes)
+    - [Dev run mode](#dev-run-mode)
+    - [Prod run mode](#prod-run-mode)
+
 ## Options
 
 - `dataDir` / `--data-dir`: path to the directory where data from Static Suite is stored. Required.
@@ -15,6 +64,7 @@ Data Server supports static JSON includes (`entityInclude`, `configInclude`, `lo
 - `dumpDir` / `--dump-dir`: path to the directory where data from Static Suite is dumped after being processed by Data Server. Optional.
 - `queryDir` / `--query-dir`: path to the directory where queries are stored. Optional.
 - `hookDir` / `--hook-dir`: path to the directory where hooks are stored. Optional.
+- `taskDir` / `--task-dir`: path to the directory where tasks are stored. Optional.
 - `logLevel` / `--log-level`: log level verbosity: `error`, `warn`, `info` or `debug`. Optional. Defaults to `info`.
 - `logFile` / `--log-file`: path to the log file. Data server logs its errors to the stdOut, but they can also be saved into a log file. Optional.
 - `logFileLevel` / `--log-file-level`: log level verbosity for the log file: `error`, `warn`, `info` or `debug`. Optional. Defaults to the value of `logLevel` / `--log-level`
@@ -344,7 +394,7 @@ Received parameters:
 
 - `config`: object with configuration options defined at Data Server start: `dataDir`, `workDir`, `queryDir`, etc
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 
 #### `onStoreLoadStart({ store, logger, dependencyTagger }): void`
 
@@ -353,7 +403,7 @@ Called before the store starts loading for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 
 #### `onProcessFile({ store, logger, dependencyTagger, relativeFilepath, fileContent }): fileContent`
@@ -363,7 +413,7 @@ Called after a file is read from disk, before adding it to the store. It is aime
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `fileContent`: file contents, an object with "raw" and "json" members.
@@ -379,7 +429,7 @@ Called after a file is added into the store for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -391,7 +441,7 @@ Called after the store finishes loading for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 
 #### `onStoreChangeStart({ store, logger, dependencyTagger, changedFiles }): void`
@@ -401,7 +451,7 @@ Called before the store starts updating.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `changedFiles`: a group of changed files in Static Suite's data dir, an object with the following keys:
   - `fromUniqueId`: a unique id representing the date from which those changes are obtained.
@@ -417,7 +467,7 @@ Called before a file is updated in the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -429,7 +479,7 @@ Called after a file is updated in the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -442,7 +492,7 @@ Called after a file is deleted from the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -454,7 +504,7 @@ Called after the store ends updating.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `changedFiles`: a group of changed files in Static Suite's data dir, an object with the following keys:
   - `fromUniqueId`: a unique id representing the date from which those changes are obtained.
@@ -591,6 +641,67 @@ const listContentsByTermId = ({ store, args }) => {
 module.exports.default = listContentsByTermId;
 ```
 
+## Tasks
+
+Data Server allows the execution of custom tasks. Just like [queries](#queries) and [hooks](#hooks), tasks are stored in a file inside a directory defined by the `taskDir` / `--task-dir` option.
+
+Each task is a file named `${queryId}.task.js`, and it must export a default function that receives an object as an argument, containing two keys (`store` and `args`):
+
+- `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
+
+- `args`: object with arguments used by that task.
+
+> PLEASE NOTE: since `store` is a shared object, you MUST NOT alter it from your tasks.
+
+Tasks must return an object with the following keys:
+
+- `result`: the list of returned results. It must be an structure representable as JSON (an object, array, string, etc)
+- `contentType`: optional content-type for the `result` field. Defaults to `application/json`.
+- `httpStatus`: optional HTTP status for the data available in "result". Defaults to 200.
+
+Example: get customized content data
+
+```javascript
+const getComponentChunkName = page => {
+  const bundle = page.data.content.bundle.replace(/_/g, '-');
+  return `component---src-views-${bundle}-${bundle}-jsx`;
+};
+
+const getPageDataObject = page => ({
+  componentChunkName: getComponentChunkName(page),
+  path: page.data.content.url.path,
+  result: {
+    pageContext: {
+      node: page,
+    },
+  },
+  staticQueryHashes: [],
+});
+
+const getPageData = ({ store, args }) => {
+  let pageData;
+  const pathFromArgs = args.path?.trim();
+  if (pathFromArgs) {
+    const path = pathFromArgs.trim().replace(/^\/+|\/+$/g, '');
+    const storeKey = path === 'index' ? '/' : `/${path}`;
+    const storeFile = store.index.url.get(storeKey);
+    if (storeFile !== undefined) {
+      pageData = getPageDataObject(storeFile);
+    }
+  }
+
+  const res = {
+    httpStatus: pageData ? 200 : 404,
+    result: pageData || 'not found',
+    contentType: pageData ? 'application/json' : 'text/plain',
+  };
+
+  return res;
+};
+
+module.exports.default = getPageData;
+```
+
 ## Dumps
 
 Data Server is able to detect when a file is being used (included) by other file. When a file changes, Data Server provides a list of all files affected by that change. This list can therefore be used to generate incremental builds of your site, building only the HTML pages for those changed files.
@@ -801,6 +912,7 @@ It watches for changes in the post processor and query files:
 
 - When a file inside the `queryDir` / `--query-dir` changes, all files inside that directory are reloaded to ensure any module or sub module is properly refreshed
 - When a file inside the `hookDir` / `--hook-dir` changes, all files inside that directory are reloaded, and the store is reloaded and passed again through all hooks, so any changes in them are applied to all data files.
+- When a file inside the `taskDir` / `--task-dir` changes, all files inside that directory are reloaded.
 
 This is the intended mode when developing queries (executing it by directly requesting the HTTP endpoint to execute a query). This mode is not required for the develop phase of a SSG, since the SSG will get the data from the Data Server only once.
 

package/dist/bin/serve.js

@@ -77,11 +77,6 @@ const argv = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         describe: 'Show help',
         type: 'boolean',
     },
-})
-    .completion('completion', (_current, _argv, done) => {
-    setTimeout(() => {
-        done(['query-dir', 'data-dir']);
-    }, 500);
 })
     .config(config)
     .parseSync();

package/dist/http/README.md

@@ -8,6 +8,55 @@ A flexible, fast and developer friendly Data Server for [Static Suite](https://w
 
 Data Server supports static JSON includes (`entityInclude`, `configInclude`, `localeInclude` and `customInclude`) and the dynamic `queryInclude`, keeping track of the relationships between includes and data: when a file changes, it knows which other files should also change, thus enabling _incremental builds_ for any kind of SSG (Gatsby, Next.js, etc).
 
+- [Static Suite Data Server](#static-suite-data-server)
+  - [Options](#options)
+  - [Options from file.](#options-from-file)
+  - [Usage](#usage)
+    - [SSG develop/build phase](#ssg-developbuild-phase)
+    - [Previewing a content from Drupal](#previewing-a-content-from-drupal)
+    - [Developing/debugging queries on a local environment](#developingdebugging-queries-on-a-local-environment)
+  - [Data structure](#data-structure)
+    - [Store internal structure](#store-internal-structure)
+    - [Getting a file](#getting-a-file)
+    - [Getting a subset of files](#getting-a-subset-of-files)
+      - [Subset options](#subset-options)
+      - [Return value](#return-value)
+    - [Getting a subset of files via HTTP](#getting-a-subset-of-files-via-http)
+      - [Return value](#return-value-1)
+    - [Indexes](#indexes)
+      - [Custom indexes](#custom-indexes)
+  - [Queries](#queries)
+  - [Hooks](#hooks)
+    - [Available hooks](#available-hooks)
+      - [`onModuleLoad({config, store, logger }): void`](#onmoduleloadconfig-store-logger--void)
+      - [`onStoreLoadStart({ store, logger, dependencyTagger }): void`](#onstoreloadstart-store-logger-dependencytagger--void)
+      - [`onProcessFile({ store, logger, dependencyTagger, relativeFilepath, fileContent }): fileContent`](#onprocessfile-store-logger-dependencytagger-relativefilepath-filecontent--filecontent)
+      - [`onStoreItemAdd({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitemadd-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreLoadDone({ store, logger, dependencyTagger }): void`](#onstoreloaddone-store-logger-dependencytagger--void)
+      - [`onStoreChangeStart({ store, logger, dependencyTagger, changedFiles }): void`](#onstorechangestart-store-logger-dependencytagger-changedfiles--void)
+      - [`onStoreItemBeforeUpdate({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitembeforeupdate-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreItemAfterUpdate({ store, logger, dependencyTagger, relativeFilepath, storeItem, previousStoreItem }): void`](#onstoreitemafterupdate-store-logger-dependencytagger-relativefilepath-storeitem-previousstoreitem--void)
+      - [`onStoreItemDelete({ store, logger, dependencyTagger, relativeFilepath, storeItem }): void`](#onstoreitemdelete-store-logger-dependencytagger-relativefilepath-storeitem--void)
+      - [`onStoreChangeDone({ store, logger, dependencyTagger, changedFiles }): void`](#onstorechangedone-store-logger-dependencytagger-changedfiles--void)
+      - [`onDumpCreate(options: OnDumpHookOptions): Dump`](#ondumpcreateoptions-ondumphookoptions-dump)
+    - [Hook example](#hook-example)
+      - [`File taxonomy.hook.js`](#file-taxonomyhookjs)
+      - [`File listContentsByTermId.query.js`](#file-listcontentsbytermidqueryjs)
+  - [Tasks](#tasks)
+  - [Dumps](#dumps)
+  - [Dependency tags](#dependency-tags)
+    - [Dependency tagger](#dependency-tagger)
+      - [`setDependency(tag: string, dependsOnTags: string[]): void`](#setdependencytag-string-dependsontags-string-void)
+      - [`addDependency(tag: string, dependsOnTags: string[]): void`](#adddependencytag-string-dependsontags-string-void)
+      - [`deleteDependency(tag: string, dependsOnTags?: string[]): void`](#deletedependencytag-string-dependsontags-string-void)
+      - [`invalidateTags(tags: string[]): void`](#invalidatetagstags-string-void)
+    - [Dependency tags example](#dependency-tags-example)
+      - [`File taxonomy.hook.js`](#file-taxonomyhookjs-1)
+      - [`File listContentsByTermId.query.js`](#file-listcontentsbytermidqueryjs-1)
+  - [Run modes](#run-modes)
+    - [Dev run mode](#dev-run-mode)
+    - [Prod run mode](#prod-run-mode)
+
 ## Options
 
 - `dataDir` / `--data-dir`: path to the directory where data from Static Suite is stored. Required.
@@ -15,6 +64,7 @@ Data Server supports static JSON includes (`entityInclude`, `configInclude`, `lo
 - `dumpDir` / `--dump-dir`: path to the directory where data from Static Suite is dumped after being processed by Data Server. Optional.
 - `queryDir` / `--query-dir`: path to the directory where queries are stored. Optional.
 - `hookDir` / `--hook-dir`: path to the directory where hooks are stored. Optional.
+- `taskDir` / `--task-dir`: path to the directory where tasks are stored. Optional.
 - `logLevel` / `--log-level`: log level verbosity: `error`, `warn`, `info` or `debug`. Optional. Defaults to `info`.
 - `logFile` / `--log-file`: path to the log file. Data server logs its errors to the stdOut, but they can also be saved into a log file. Optional.
 - `logFileLevel` / `--log-file-level`: log level verbosity for the log file: `error`, `warn`, `info` or `debug`. Optional. Defaults to the value of `logLevel` / `--log-level`
@@ -344,7 +394,7 @@ Received parameters:
 
 - `config`: object with configuration options defined at Data Server start: `dataDir`, `workDir`, `queryDir`, etc
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 
 #### `onStoreLoadStart({ store, logger, dependencyTagger }): void`
 
@@ -353,7 +403,7 @@ Called before the store starts loading for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 
 #### `onProcessFile({ store, logger, dependencyTagger, relativeFilepath, fileContent }): fileContent`
@@ -363,7 +413,7 @@ Called after a file is read from disk, before adding it to the store. It is aime
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `fileContent`: file contents, an object with "raw" and "json" members.
@@ -379,7 +429,7 @@ Called after a file is added into the store for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -391,7 +441,7 @@ Called after the store finishes loading for the first time.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 
 #### `onStoreChangeStart({ store, logger, dependencyTagger, changedFiles }): void`
@@ -401,7 +451,7 @@ Called before the store starts updating.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `changedFiles`: a group of changed files in Static Suite's data dir, an object with the following keys:
   - `fromUniqueId`: a unique id representing the date from which those changes are obtained.
@@ -417,7 +467,7 @@ Called before a file is updated in the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -429,7 +479,7 @@ Called after a file is updated in the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -442,7 +492,7 @@ Called after a file is deleted from the store.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `relativeFilepath`: relative file path inside the data dir.
 - `storeItem`: contents of the store item.
@@ -454,7 +504,7 @@ Called after the store ends updating.
 Received parameters:
 
 - `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
-- `logger`: the logger service width several functions to log messages: `error()`, `warn()`, `info()`, `error()`
+- `logger`: the logger service with several functions to log messages: `error()`, `warn()`, `info()`, `error()`
 - `dependencyTagger`: the dependency tagger service. See [Dependency Tags](#dependency-tags) section.
 - `changedFiles`: a group of changed files in Static Suite's data dir, an object with the following keys:
   - `fromUniqueId`: a unique id representing the date from which those changes are obtained.
@@ -591,6 +641,67 @@ const listContentsByTermId = ({ store, args }) => {
 module.exports.default = listContentsByTermId;
 ```
 
+## Tasks
+
+Data Server allows the execution of custom tasks. Just like [queries](#queries) and [hooks](#hooks), tasks are stored in a file inside a directory defined by the `taskDir` / `--task-dir` option.
+
+Each task is a file named `${queryId}.task.js`, and it must export a default function that receives an object as an argument, containing two keys (`store` and `args`):
+
+- `store`: the object that holds all data. See [store internal structure](#store-internal-structure).
+
+- `args`: object with arguments used by that task.
+
+> PLEASE NOTE: since `store` is a shared object, you MUST NOT alter it from your tasks.
+
+Tasks must return an object with the following keys:
+
+- `result`: the list of returned results. It must be an structure representable as JSON (an object, array, string, etc)
+- `contentType`: optional content-type for the `result` field. Defaults to `application/json`.
+- `httpStatus`: optional HTTP status for the data available in "result". Defaults to 200.
+
+Example: get customized content data
+
+```javascript
+const getComponentChunkName = page => {
+  const bundle = page.data.content.bundle.replace(/_/g, '-');
+  return `component---src-views-${bundle}-${bundle}-jsx`;
+};
+
+const getPageDataObject = page => ({
+  componentChunkName: getComponentChunkName(page),
+  path: page.data.content.url.path,
+  result: {
+    pageContext: {
+      node: page,
+    },
+  },
+  staticQueryHashes: [],
+});
+
+const getPageData = ({ store, args }) => {
+  let pageData;
+  const pathFromArgs = args.path?.trim();
+  if (pathFromArgs) {
+    const path = pathFromArgs.trim().replace(/^\/+|\/+$/g, '');
+    const storeKey = path === 'index' ? '/' : `/${path}`;
+    const storeFile = store.index.url.get(storeKey);
+    if (storeFile !== undefined) {
+      pageData = getPageDataObject(storeFile);
+    }
+  }
+
+  const res = {
+    httpStatus: pageData ? 200 : 404,
+    result: pageData || 'not found',
+    contentType: pageData ? 'application/json' : 'text/plain',
+  };
+
+  return res;
+};
+
+module.exports.default = getPageData;
+```
+
 ## Dumps
 
 Data Server is able to detect when a file is being used (included) by other file. When a file changes, Data Server provides a list of all files affected by that change. This list can therefore be used to generate incremental builds of your site, building only the HTML pages for those changed files.
@@ -801,6 +912,7 @@ It watches for changes in the post processor and query files:
 
 - When a file inside the `queryDir` / `--query-dir` changes, all files inside that directory are reloaded to ensure any module or sub module is properly refreshed
 - When a file inside the `hookDir` / `--hook-dir` changes, all files inside that directory are reloaded, and the store is reloaded and passed again through all hooks, so any changes in them are applied to all data files.
+- When a file inside the `taskDir` / `--task-dir` changes, all files inside that directory are reloaded.
 
 This is the intended mode when developing queries (executing it by directly requesting the HTTP endpoint to execute a query). This mode is not required for the develop phase of a SSG, since the SSG will get the data from the Data Server only once.
 

package/dist/http/routes/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/http/routes/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,QAAA,MAAM,UAAU,QAAS,OAAO,OAAO,QAAQ,KAAG,IAMjD,CAAC;AAEF,QAAA,MAAM,QAAQ,QAAS,OAAO,OAAO,QAAQ,KAAG,IAQ/C,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/http/routes/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,QAAA,MAAM,UAAU,QAAS,OAAO,OAAO,QAAQ,KAAG,IAMjD,CAAC;AAEF,QAAA,MAAM,QAAQ,QAAS,OAAO,OAAO,QAAQ,KAAG,IAa/C,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC"}

package/dist/http/routes/query.js

@@ -15,7 +15,11 @@ const runQuery = (req, res) => {
     const queryDefinition = req.originalUrl.replace(/^\/query\//, '');
     const response = query_1.queryRunner.run(queryDefinition);
     res.status(200);
-    res.set('application/json');
+    res.set({
+        'Content-Type': 'metadata' in response
+            ? response.metadata.contentType
+            : 'application/json',
+    });
     res.send(response);
 };
 exports.runQuery = runQuery;

package/dist/http/routes/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/http/routes/task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,QAAA,MAAM,SAAS,QAAS,OAAO,OAAO,QAAQ,KAAG,IAKhD,CAAC;AAEF,QAAA,MAAM,OAAO,QAAS,OAAO,OAAO,QAAQ,KAAG,IAW9C,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/http/routes/task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,QAAA,MAAM,SAAS,QAAS,OAAO,OAAO,QAAQ,KAAG,IAKhD,CAAC;AAEF,QAAA,MAAM,OAAO,QAAS,OAAO,OAAO,QAAQ,KAAG,IAoB9C,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC"}

package/dist/http/routes/task.js

@@ -15,8 +15,14 @@ const runTask = (req, res) => {
     const args = req.query;
     const taskId = req.params[0];
     const response = task_1.taskRunner.run(taskId, args);
-    res.status(200);
-    res.set('application/json');
-    res.send(response);
+    res.status('metadata' in response && response.metadata.httpStatus
+        ? response.metadata.httpStatus
+        : 200);
+    res.set({
+        'Content-Type': 'metadata' in response
+            ? response.metadata.contentType
+            : 'application/json',
+    });
+    res.send('data' in response ? response.data : response);
 };
 exports.runTask = runTask;

package/dist/lib/task/task.types.d.ts

@@ -63,6 +63,12 @@ export type TaskModuleResult = {
      * @defaultValue 'application/json'
      */
     contentType?: string;
+    /**
+     * Optional HTTP status type for the data available in "result"
+     *
+     * @defaultValue 200
+     */
+    httpStatus?: number;
 };
 /**
  * A successful response returned after executing a task.
@@ -95,6 +101,12 @@ export type TaskSuccessfulResponse = {
          * Execution time taken by the task, in milliseconds.
          */
         execTimeMs: number;
+        /**
+         * Optional HTTP status type for the data available in "data"
+         *
+         * @defaultValue 200
+         */
+        httpStatus?: number;
     };
 };
 /**

package/dist/lib/task/task.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.types.d.ts","sourceRoot":"","sources":["../../../src/lib/task/task.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,GACb,sBAAsB,GAAG,iBAAiB,CAAC;CAC/C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,MAAM,EAAE,GAAG,CAAC;IAEZ;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,IAAI,EAAE,GAAG,CAAC;IAEV;;OAEG;IACH,QAAQ,EAAE;QACR;;;;;;;WAOG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;WAEG;QACH,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,GAAG,gBAAgB,CAAC;CACtE,CAAC;AACF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iBAChB,sBAAsB,GAAG,iBAAiB,sCAED,CAAC"}
+{"version":3,"file":"task.types.d.ts","sourceRoot":"","sources":["../../../src/lib/task/task.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,GACb,sBAAsB,GAAG,iBAAiB,CAAC;CAC/C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,MAAM,EAAE,GAAG,CAAC;IAEZ;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,IAAI,EAAE,GAAG,CAAC;IAEV;;OAEG;IACH,QAAQ,EAAE;QACR;;;;;;;WAOG;QACH,WAAW,EAAE,MAAM,CAAC;QAEpB;;WAEG;QACH,UAAU,EAAE,MAAM,CAAC;QAEnB;;;;WAIG;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,GAAG,gBAAgB,CAAC;CACtE,CAAC;AACF;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iBAChB,sBAAsB,GAAG,iBAAiB,sCAED,CAAC"}

package/dist/lib/task/taskRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taskRunner.d.ts","sourceRoot":"","sources":["../../../src/lib/task/taskRunner.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,UAAU,EAIX,MAAM,cAAc,CAAC;AAkBtB,eAAO,MAAM,UAAU,EAAE,UAkDxB,CAAC"}
+{"version":3,"file":"taskRunner.d.ts","sourceRoot":"","sources":["../../../src/lib/task/taskRunner.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,UAAU,EAIX,MAAM,cAAc,CAAC;AAkBtB,eAAO,MAAM,UAAU,EAAE,UAoDxB,CAAC"}

package/dist/lib/task/taskRunner.js

@@ -42,6 +42,7 @@ exports.taskRunner = {
         const taskResult = {
             result: undefined,
             contentType: undefined,
+            httpStatus: undefined,
         };
         try {
             const taskModule = taskModuleInfo.getModule();
@@ -51,6 +52,7 @@ exports.taskRunner = {
             });
             taskResult.result = taskResponse?.result;
             taskResult.contentType = taskResponse?.contentType || 'application/json';
+            taskResult.httpStatus = taskResponse?.httpStatus || 200;
         }
         catch (e) {
             // Log error and rethrow.
@@ -63,6 +65,7 @@ exports.taskRunner = {
             metadata: {
                 contentType: taskResult.contentType || 'application/json',
                 execTimeMs,
+                httpStatus: taskResult.httpStatus || 200,
             },
         };
         logger_1.logger.debug(`#${count} Task "${taskId}" took ${execTimeMs} ms.`);

package/dist/lib/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.9"
+      "packageVersion": "7.52.11"
     }
   ]
 }

package/dist/static-suite-data-server.d.ts

@@ -540,6 +540,12 @@ declare type TaskSuccessfulResponse = {
          * Execution time taken by the task, in milliseconds.
          */
         execTimeMs: number;
+        /**
+         * Optional HTTP status type for the data available in "data"
+         *
+         * @defaultValue 200
+         */
+        httpStatus?: number;
     };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@static-suite/static-suite-data-server",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "A flexible, fast and developer friendly Data Server for Static Suite",
   "main": "./dist/lib/index.js",
   "typings": "./dist/lib/index.d.ts",
@@ -85,4 +85,4 @@
       "src/__tests__/mocks/*"
     ]
   }
-}
+}

package/src/bin/serve.ts

@@ -79,11 +79,6 @@ const argv = yargs(hideBin(process.argv))
       type: 'boolean',
     },
   })
-  .completion('completion', (_current, _argv, done) => {
-    setTimeout(() => {
-      done(['query-dir', 'data-dir']);
-    }, 500);
-  })
   .config(config)
   .parseSync();
 

package/src/http/routes/query.ts

@@ -20,7 +20,12 @@ const runQuery = (req: Request, res: Response): void => {
   const response: QuerySuccessfulResponse | QueryErrorResponse =
     queryRunner.run(queryDefinition);
   res.status(200);
-  res.set('application/json');
+  res.set({
+    'Content-Type':
+      'metadata' in response
+        ? response.metadata.contentType
+        : 'application/json',
+  });
   res.send(response);
 };
 

package/src/http/routes/task.ts

@@ -21,9 +21,18 @@ const runTask = (req: Request, res: Response): void => {
     taskId,
     args,
   );
-  res.status(200);
-  res.set('application/json');
-  res.send(response);
+  res.status(
+    'metadata' in response && response.metadata.httpStatus
+      ? response.metadata.httpStatus
+      : 200,
+  );
+  res.set({
+    'Content-Type':
+      'metadata' in response
+        ? response.metadata.contentType
+        : 'application/json',
+  });
+  res.send('data' in response ? response.data : response);
 };
 
 export { taskIndex, runTask };

package/src/lib/task/task.types.ts

@@ -70,6 +70,13 @@ export type TaskModuleResult = {
    * @defaultValue 'application/json'
    */
   contentType?: string;
+
+  /**
+   * Optional HTTP status type for the data available in "result"
+   *
+   * @defaultValue 200
+   */
+  httpStatus?: number;
 };
 
 /**
@@ -105,6 +112,13 @@ export type TaskSuccessfulResponse = {
      * Execution time taken by the task, in milliseconds.
      */
     execTimeMs: number;
+
+    /**
+     * Optional HTTP status type for the data available in "data"
+     *
+     * @defaultValue 200
+     */
+    httpStatus?: number;
   };
 };
 

package/src/lib/task/taskRunner.ts

@@ -46,6 +46,7 @@ export const taskRunner: TaskRunner = {
     const taskResult: TaskModuleResult = {
       result: undefined,
       contentType: undefined,
+      httpStatus: undefined,
     };
     try {
       const taskModule = taskModuleInfo.getModule();
@@ -54,8 +55,8 @@ export const taskRunner: TaskRunner = {
         args,
       });
       taskResult.result = taskResponse?.result;
-
       taskResult.contentType = taskResponse?.contentType || 'application/json';
+      taskResult.httpStatus = taskResponse?.httpStatus || 200;
     } catch (e) {
       // Log error and rethrow.
       logger.error(
@@ -69,6 +70,7 @@ export const taskRunner: TaskRunner = {
       metadata: {
         contentType: taskResult.contentType || 'application/json',
         execTimeMs,
+        httpStatus: taskResult.httpStatus || 200,
       },
     };