feat: add index resolution for modules, resources and segments

documentation/docs/.vitepress/config.ts

@@ -48,6 +48,13 @@ export default defineConfig({
           { text: 'Debugging', link: '/develop/debugging' }
         ]
       },
+      {
+        text: 'BUILD',
+        items: [
+          { text: 'Settings', link: '/build/settings' },
+          { text: 'Configuration', link: '/build/configuration' }
+        ]
+      },
       {
         text: 'DEPLOY',
         items: [

documentation/docs/build/configuration.md

@@ -0,0 +1,52 @@
+---
+layout: doc
+
+prev:
+    text: Build settings
+    link: /build/settings
+
+next:
+    text: Segmentation
+    link: /deploy/segmentation
+
+---
+
+# Configuration
+
+The jitar build process is configured using a `jitar.json` file. This file is optional and defines the location of the `source`, `target`, `segments`, and `resources` folders. These values are used to split the application in separate deployable bundles and create the necessary configuration files for the jitar runtime.
+
+## Jitar configuration file
+
+The `jitar.json` file is a JSON file that contains the following properties:
+
+```json
+{
+    "source": "./src",
+    "target": "./dist",
+    "segments": "./segments",
+    "resources": "./resources"
+}
+```
+
+There are four properties in the configuration file:
+* `source` - the location of the source files (default `./src`).
+* `target` - the location of the target files (default `./dist`).
+* `segments` - the location of the segment configuration files (default `./segments`).
+* `resources` - the location of the resource files (default `./resources`).
+
+::: tip NOTE
+For a TypeScript project, the `source` folder should be the target folder after transpilation, so it should be `./dist` instead of `./src`. The `target` folder can be the same as the `source` folder in this case, but it can also be a different folder.
+:::
+
+::: tip NOTE
+The build process deletes the files in the `target` folder during the build process. Make sure that it doesn't point to the `src` folder.
+:::
+
+::: tip NOTE
+The configuration also supports environment variables. They can be used by wrapping the variable name in `${}`. For example, `${source}`.
+```json
+{
+    "source": "${source}"
+}
+```
+:::

documentation/docs/build/settings.md

@@ -0,0 +1,32 @@
+---
+layout: doc
+
+prev:
+    text: Debugging
+    link: /develop/debugging
+
+next:
+    text: Build configuration
+    link: /build/configuration
+
+---
+
+# Settings
+
+The build process accepts a few command line arguments to configure its build behavior. A fully configured command line looks like this:
+
+```bash
+jitar build --env-file=.env --log-level=info --config=jitar.json
+```
+
+## Environment file
+
+The `--env-file` argument can be used to specify a file that contains environment variables. This is an optional argument without a default value.
+
+## Log level
+
+To control the level of logging, the optional `--log-level` argument can be used. The default for this value is `info`. A more elaborate description of the log levels can be found in the [logging](../monitor/logging) section.
+
+## Configuration file
+
+To control the input and output of the build process. The `--config` argument can be used to specify a configuration file. This is an optional argument with the default value `jitar.json`.

documentation/docs/deploy/resources.md

@@ -19,12 +19,12 @@ In Jitar's [segmentation model](/deploy/segmentation), each segment is isolated
 
 ### Resource files
 
-Jitar will search for resource definitions files in the project directory. The files are named `*.resources.json`. Each entry defines the entry point of the `module` that should be used as a resource.
+Jitar will search for resource definitions files in the `resources` directory. The files are named `*.json`. Each entry defines the entry point of the `module` that should be used as a resource.
 
 The file has the following structure:
 
 ```json
-// app.resources.json
+// app.json
 [
     "./integrations/authentication/entry-file",
     "./integrations/database/index",

documentation/docs/deploy/segmentation.md

@@ -2,8 +2,8 @@
 layout: doc
 
 prev:
-    text: Debugging
-    link: /develop/debugging
+    text: Build configuration
+    link: /build/configuration
 
 next:
     text: Resources
@@ -13,7 +13,7 @@ next:
 
 # Segmentation
 
-Segments are used to break applications down into distributable pieces. A segment groups module files that need to be deployed together. Its definition is placed into a JSON segment file. Let's look at a simple example file named `default.segment.json`.
+Segments are used to break applications down into distributable pieces. A segment groups module files that need to be deployed together. Its definition is placed into a JSON segment file. Let's look at a simple example file named `default.json`.
 
 ```json
 {
@@ -28,13 +28,9 @@ This example includes the `sayHello` function from the `domain/sayHello.ts` modu
 
 ### Naming and placement
 
-Jitar uses the configuration filename for identifying segments. There is no mandatory location for placing segment configuration files, so Jitar uses the `.segment.json` extension for scanning them in the project.
+Jitar uses the configuration filename for identifying segments. The default location for placing segment configuration files is `./segments`.
 
-Segments are named, and their names are derived from the filename. Everything that is in front of the `.segment.json` extension is used as the name. So for the filename `default.segment.json` the segment is named 'default'.
-
-::: info NOTE
-Although there is no mandatory location for these files, we always place them in a segment folder in the root directory of the project. We've done this for all our projects and examples and made finding them very easy.
-:::
+Segments are named, and their names are derived from the filename. Everything that is in front of the `.json` extension is used as the name. So for the filename `default.json` the segment is named 'default'.
 
 ### Configuration structure
 

documentation/docs/develop/application-structure.md

@@ -21,6 +21,7 @@ At the root level of a project we use at least the following subfolders.
 
 ```txt
 .
+├─ resources
 ├─ segments
 ├─ services
 ├─ src
@@ -29,6 +30,7 @@ At the root level of a project we use at least the following subfolders.
 
 Although the names are quite self explanatory, this how we use them:
 
+* resources - contains all resource configuration files;
 * segments - contains all segment configuration files;
 * services - contains all service configuration files;
 * src - contains all application code;
@@ -54,11 +56,10 @@ src
 │  ├─ downloads
 │  ├─ images
 │  ├─ ...
-├─ integrations
-│  ├─ database
-│  ├─ notifications
-│  ├─ ...
-└─ jitar.ts
+└─ integrations
+   ├─ database
+   ├─ notifications
+   ├─ ...
 ```
 
 Each folder has it's own responsibility:
@@ -100,23 +101,22 @@ test
 │  ├─ downloads
 │  ├─ images
 │  ├─ ...
-├─ integrations
-│  ├─ database
-│  ├─ notifications
-│  ├─ ...
-└─ jitar.ts
+└─ integrations
+   ├─ database
+   ├─ notifications
+   ├─ ...
 ```
 
 By keeping a 1-on-1 relation with the source files makes it easy to find the associated tests.
 
 ## Segments
 
-The `segments` folder contains all [segment configuration](../fundamentals/building-blocks#segments) files. Although Jitar doesn't care about their location, we find it more clear to group them here.
+The `segments` folder contains all [segment configuration](../fundamentals/building-blocks#segments) files.
 
 ```txt
 segments
-├─ first.segment.json
-└─ second.segment.json
+├─ first.json
+└─ second.json
 ```
 
 Defining the right segments heavily depends on the application and how it is used. A single client / server application may suffice with a 'client' and 'server' segment. Other (larger) applications might benefit from segmentation by concept like 'account' or 'reporting'.
@@ -125,7 +125,7 @@ We recommend defining the segments as late as possible, and only add them for re
 
 ## Services
 
-The `services` folder contains all [service configuration](../fundamentals/runtime-services) files. Just like the segments, Jitar doesn't care about their location, but we do.
+The `services` folder contains all [service configuration](../fundamentals/runtime-services) files. Jitar doesn't care about their location, but we do.
 
 ```txt
 services
@@ -140,3 +140,14 @@ services
 The required services depend on the segmentation needs of the application. Applications that do not need any scaling or replication can suffice with a standalone service. Otherwise multiple services are needed to run the application. We always make sure the configuration name reflects its service type.
 
 We always add a standalone configuration, even if the application is deployed with multiple services. We use this configuration for developing the application to simplify the development setup.
+
+## Resources
+
+The `resources` folder contains all [resource configuration](../deploy/resources) files.
+
+```txt
+services
+└─ global.json
+```
+
+Any resource that needs to be initialized in a startup or stopped in a teardown phase must be defined here.

documentation/docs/develop/data-sharing.md

@@ -153,11 +153,11 @@ import { modify } from './modify';
 export async function test(): Promise<void>
 {
     // create new instance
-    const person: Person = new Person( 'John Doe', 42);
+    const original = new Person( 'John Doe', 42);
 
-    modify(person);
+    const copy = await modify(original);
 
-    console.log(person);
+    console.log(copy);
 }
 ```
 

documentation/docs/develop/debugging.md

@@ -6,8 +6,8 @@ prev:
     link: /develop/assets
 
 next:
-    text: Segmentation
-    link: /deploy/segmentation
+    text: Build settings
+    link: /build/settings
 
 ---
 

documentation/docs/develop/error-handling.md

@@ -31,11 +31,11 @@ export DatabaseError extends Error
 ```ts
 // src/domain/account/storeAccount.ts
 import { Account } from './Account';
-import { DatabaseError } from '../DatabaseError';
+import { DatabaseError } from '../../DatabaseError';
 
 export async function storeAccount(account: Account): Promise<void>
 {
-    throw new Error('Not implemented');
+    throw new DatabaseError('Not implemented');
 }
 ```
 

documentation/docs/fundamentals/building-blocks.md

@@ -47,7 +47,7 @@ More in depth information on writing functions and the rules can be found in the
 
 ### Fully qualified name (FQN)
 
-Every function has a unique name used for internal and external identification. This name is called a fully qualified name (FQN) and constructed with the location and the name of the function in the following format.
+Every function has a unique name used for internal and external identification. This name is called the fully qualified name (FQN) and constructed with the location and the name of the function in the following format.
 
 ```txt
 { location relative to the source folder }/{ function name }
@@ -110,10 +110,10 @@ This class complies with the rules because all the exposed values (name and age)
 
 Segments are used to break applications down into distributable pieces. Jitar's segmentation system is module oriented. This means that a segment groups module files that need to be deployed together.
 
-For the definition of a segment, JSON files are used with the '.segment.json' extension. These files contain the segment configuration. Let's see how a simple configuration looks like.
+For the definition of a segment, JSON files are used and placed in a `segments` folder. These files contain the segment configuration. Let's see how a simple configuration looks like.
 
 ```json
-// default.segment.json
+// segments/default.json
 {
     "./domain/sayHello":
     {
@@ -133,7 +133,7 @@ For the definition of a segment, JSON files are used with the '.segment.json' ex
 This configuration connects very well with the JavaScript module system. It includes exported functions from one or more module files with four configuration options:
 
 1. Exposed functions per module file
-1. Access level per function (public / private, default private)
+1. Access level per function (public / protected / private, default private)
 1. Version number per function (optional, default 0.0.0)
 1. Alternative name (optional, default the name of the function)
 

documentation/docs/introduction/quick-start.md

@@ -73,13 +73,13 @@ Besides functions there are more useful building blocks. You can find out more i
 To tell Jitar if a function runs on the client or the server, the application is split into groups of modules, called segments. Each segment has its own configuration file. In the project we can find one in the `segments` folder.
 
 ```json
-// segments/default.segment.json
+// segments/default.json
 {
     "./domain/sayHello": { "sayHello": { "access": "public" } }
 }
 ```
 
-Segments are named, and their names are stored in the filename. In this case the segment is called ‘default’. The rest of the filename makes it a detectable segment configuration, because Jitar scans the project to find them.
+Segments are named, and their names are stored in the filename. In this case the segment is called ‘default’.
 
 Segment configurations work like the JavaScript module system. In this case we export the `sayHello` function from `./domain/sayHello` module file. Additionally we set the access level to public so it can be called from the client. The configuration can be extended by simply adding functions.
 

examples/access-protection/README.md

@@ -18,8 +18,8 @@ The procedure to get the secret has been made private to ensure it isn't accessi
 
 **Segments**
 
-* Web - contains the *web* procedures (`segments/web.segment.json`)
-* Game - contains the *game* procedures (`segments/game.segment.json`)
+* Web - contains the *web* procedures (`segments/web.json`)
+* Game - contains the *game* procedures (`segments/game.json`)
 
 **Services**
 

examples/construction/README.md

@@ -14,7 +14,7 @@ When the application gets shut down, the database gets cleared.
 
 **Segments**
 
-* Default - contains the *getData* procedure (`segments/default.segment.json`)
+* Default - contains the *getData* procedure (`segments/default.json`)
 
 **Services**
 

examples/construction/jitar.json

@@ -1,4 +1,6 @@
 {
     "source": "./dist",
-    "target": "./.jitar"
+    "target": "./.jitar",
+    "segments": "./segments",
+    "resources": "./resources"
 }

examples/construction/resources/database.json

@@ -0,0 +1,3 @@
+[
+    "./database"
+]

examples/cors/README.md

@@ -16,7 +16,7 @@ Because Jitar and the web server both run on a different port, a CORS rule is re
 
 **Segments**
 
-* Server - contains the *server* procedures (`segments/server.segment.json`)
+* Server - contains the *server* procedures (`segments/server.json`)
 
 **Services**
 

examples/data-transportation/README.md

@@ -20,8 +20,8 @@ It contains a registration process that creates and transports a data object.
 
 **Segments**
 
-* Account - contains the *account* procedures (`segments/account.segment.json`)
-* Helpdesk - contains the *helpdesk* procedures (`segments/greeting.segment.json`)
+* Account - contains the *account* procedures (`segments/account.json`)
+* Helpdesk - contains the *helpdesk* procedures (`segments/greeting.json`)
 
 **Services**
 

examples/error-handling/README.md

@@ -19,8 +19,8 @@ Getting the data results into an error that is caught when trying to export it.
 
 **Segments**
 
-* Data - contains the *data* procedures (`segments/data.segment.json`)
-* Process - contains the *process* procedures (`segments/process.segment.json`)
+* Data - contains the *data* procedures (`segments/data.json`)
+* Process - contains the *process* procedures (`segments/process.json`)
 
 **Services**
 

examples/health-checks/README.md

@@ -17,7 +17,7 @@ There is no application for this example, only a health check that is registered
 
 **Services**
 
-* Standalone - loads no segments (`services/default.segment.json`)
+* Standalone - loads no segments (`services/default.json`)
 
 ## Running the example