You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Database naming: thedefault"data"databaseisgenerallyagooddefaultchoicefortablesinapplicationsthatwillnotbereusedinotherapplications (anddon'tneedtoworryaboutstayinginaseparatenamespace). Applicationwithmanytablesmaywishtoorganizethetablesintoseparatedatabases (but remember that transactions do not preserve atomicity across different databases, only across tables in the same database). Forcomponentsthataredesignedforre-use, itisrecommendedthatyouuseadatabasenamethatisspecifictothecomponent (e.g. "my-component-data") toavoidnamecollisionswithothercomponents.
Copy file name to clipboardExpand all lines: docs/developers/components/built-in.md
+36-12Lines changed: 36 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,13 +20,13 @@ Harper provides extended features using built-in components. They do **not** nee
20
20
21
21
Specify custom endpoints using [Fastify](https://fastify.dev/).
22
22
23
-
This component is a [Resource Extension](reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](reference.md#resource-extension-configuration) configuration options.
23
+
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`and `urlPath`](./reference.md#resource-extension-configuration) configuration options.
24
24
25
25
Complete documentation for this feature is available here: [Define Fastify Routes](../applications/define-routes.md)
26
26
27
27
```yaml
28
28
fastifyRoutes:
29
-
files: './routes/*.js'
29
+
files: 'routes/*.js'
30
30
```
31
31
32
32
## graphql
@@ -45,13 +45,13 @@ graphql: true
45
45
46
46
Specify schemas for Harper tables and resources via GraphQL schema syntax.
47
47
48
-
This component is a [Resource Extension](reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](reference.md#resource-extension-configuration) configuration options.
48
+
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`and `urlPath`](./reference.md#resource-extension-configuration) configuration options.
49
49
50
50
Complete documentation for this feature is available here: [Defining Schemas](../applications/defining-schemas.md)
51
51
52
52
```yaml
53
53
graphqlSchema:
54
-
files: './schemas.graphql'
54
+
files: 'schemas.graphql'
55
55
```
56
56
57
57
## jsResource
@@ -60,18 +60,18 @@ Specify custom, JavaScript based Harper resources.
60
60
61
61
Refer to the Application [Custom Functionality with JavaScript](../applications/#custom-functionality-with-javascript) guide, or [Resource Class](../../technical-details/reference/resource.md) reference documentation for more information on custom resources.
62
62
63
-
This component is a [Resource Extension](reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](reference.md#resource-extension-configuration) configuration options.
63
+
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`and `urlPath`](./reference.md#resource-extension-configuration) configuration options.
64
64
65
65
```yaml
66
66
jsResource:
67
-
files: './resource.js'
67
+
files: 'resource.js'
68
68
```
69
69
70
70
## loadEnv
71
71
72
72
Load environment variables via files like `.env`.
73
73
74
-
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](./reference.md#resource-extension-configuration) configuration options.
74
+
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`and `urlPath`](./reference.md#resource-extension-configuration) configuration options.
75
75
76
76
Ensure this component is specified first in `config.yaml` so that environment variables are loaded prior to loading any other components.
77
77
@@ -128,22 +128,46 @@ rest:
128
128
129
129
Specify roles for Harper tables and resources.
130
130
131
-
This component is a [Resource Extension](reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](reference.md#resource-extension-configuration) configuration options.
131
+
This component is a [Resource Extension](./reference.md#resource-extension) and can be configured with the [`files`and `urlPath`](./reference.md#resource-extension-configuration) configuration options.
132
132
133
133
Complete documentation for this feature is available here: [Defining Roles](../applications/defining-roles.md)
134
134
135
135
```yaml
136
136
roles:
137
-
files: './roles.yaml'
137
+
files: 'roles.yaml'
138
138
```
139
139
140
140
## static
141
141
142
-
Specify which files to server statically from the Harper HTTP endpoint. Built using the [send](https://www.npmjs.com/package/send) and [serve-static](https://www.npmjs.com/package/serve-static) modules.
142
+
Specify files to serve statically from the Harper HTTP endpoint.
143
143
144
-
This component is a [Resource Extension](reference.md#resource-extension) and can be configured with the [`files`, `path`, and `root`](reference.md#resource-extension-configuration) configuration options.
144
+
Use the [Resource Extension](./reference.md#resource-extension) configuration options [`files` and `urlPath`](./reference.md#resource-extension-configuration) to specify the files to be served.
145
+
146
+
As specified by Harper's Resource Extension docs, the `files` option can be any glob pattern or a glob options object. This extension will serve all files matching the pattern, so make sure to be specific.
147
+
148
+
To serve the entire `web` directory, specify `files: 'web/**'`.
149
+
150
+
To serve only the html files within `web`, specify `files: 'web/*.html'` or `files: 'web/**/*.html'`.
151
+
152
+
The `urlPath` option is the base URL path entries will be resolved to. For example, a `urlPath: 'static'` will serve all files resolved from `files` to the URL path `localhost/static/`.
153
+
154
+
Given the `config.yaml`:
145
155
146
156
```yaml
147
157
static:
148
-
files: './web/*'
158
+
files: 'web/*.html'
159
+
urlPath: 'static'
149
160
```
161
+
162
+
And the file directory structure:
163
+
164
+
```
165
+
component/
166
+
├─ web/
167
+
│ ├─ index.html
168
+
│ ├─ blog.html
169
+
├─ config.yaml
170
+
171
+
```
172
+
173
+
The HTML files will be available at `localhost/static/index.html` and `localhost/static/blog.html` respectively.
Copy file name to clipboardExpand all lines: docs/developers/components/reference.md
+49-20Lines changed: 49 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,7 +65,7 @@ And now in `config.yaml`:
65
65
```yaml
66
66
harper-nextjs-test-feature:
67
67
package: '@harperdb/nextjs'
68
-
files: '/*'
68
+
files: './'
69
69
# ...
70
70
```
71
71
@@ -84,7 +84,7 @@ jsResource:
84
84
files: 'resources.js'
85
85
fastifyRoutes:
86
86
files: 'routes/*.js'
87
-
path: '.'
87
+
urlPath: '.'
88
88
static:
89
89
files: 'web/**'
90
90
```
@@ -115,35 +115,64 @@ Furthermore, what defines an extension separately from a component is that it le
115
115
116
116
A Resource Extension is for processing a certain type of file or directory. For example, the built-in [jsResource](./built-in.md#jsresource) extension handles executing JavaScript files.
117
117
118
-
Resource Extensions are comprised of four distinct function exports, [`handleFile()`](#handlefilecontents-urlpath-path-resources-void--promisevoid), [`handleDirectory()`](#handledirectoryurlpath-path-resources-boolean--void--promiseboolean--void), [`setupFile()`](#setupfilecontents-urlpath-path-resources-void--promisevoid), and [`setupDirectory()`](#setupdirectoryurlpath-path-resources-boolean--void--promiseboolean--void). The `handleFile()` and `handleDirectory()` methods are executed on **all worker threads**, and are _executed again during restarts_. The `setupFile()` and `setupDirectory()` methods are only executed **once** on the **main thread** during the initial system start sequence.
118
+
Resource Extensions are comprised of four distinct function exports, [`handleFile()`](#handlefilecontents-urlpath-absolutepath-resources-void--promisevoid), [`handleDirectory()`](#handledirectoryurlpath-absolutepath-resources-boolean--void--promiseboolean--void), [`setupFile()`](#setupfilecontents-urlpath-absolutepath-resources-void--promisevoid), and [`setupDirectory()`](#setupdirectoryurlpath-absolutepath-resources-boolean--void--promiseboolean--void). The `handleFile()` and `handleDirectory()` methods are executed on **all worker threads**, and are _executed again during restarts_. The `setupFile()` and `setupDirectory()` methods are only executed **once** on the **main thread** during the initial system start sequence.
119
119
120
120
> Keep in mind that the CLI command `harperdb restart` or CLI argument `restart=true` only restarts the worker threads. If a component is deployed using `harperdb deploy`, the code within the `setupFile()` and `setupDirectory()` methods will not be executed until the system is completely shutdown and turned back on.
121
121
122
122
Other than their execution behavior, the `handleFile()` and `setupFile()` methods, and `handleDirectory()` and `setupDirectory()` methods have identical function definitions (arguments and return value behavior).
123
123
124
124
#### Resource Extension Configuration
125
125
126
-
Any [Resource Extension](#resource-extension) can be configured with the `files`, `path`, and `root` options. These options control how _files_ and _directories_ are resolved in order to be passed to the extension's `handleFile()`, `setupFile()`, `handleDirectory()`, and `setupDirectory()` methods.
126
+
Any [Resource Extension](#resource-extension) can be configured with the `files`and `path` options. These options control how _files_ and _directories_ are resolved in order to be passed to the extension's `handleFile()`, `setupFile()`, `handleDirectory()`, and `setupDirectory()` methods.
127
127
128
-
- **files** - `string` - *required* - Specifies the set of files and directories that should be handled by the component. Can be a glob pattern.
129
-
- **path** - `string` - *optional* - Specifies the URL path to be handled by the component.
130
-
- **root** - `string` - *optional* - Specifies the root directory for mapping file paths to the URLs.
128
+
- **files** - `string | string[] | Object` - *required* - A [glob pattern](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax) string, array of glob pattern strings, or a more expressive glob options object determining the set of files and directories to be resolved for the extension. If specified as an object, the `source` property is required. By default, Harper matches files *and directories*.
129
+
- **source** - `string | string[]` - *required* - The glob pattern string or array of strings.
130
+
- **onlyFiles** - `boolean` - *optional* - Defaults to `false`, meaning the glob pattern will match directories and files.
131
+
- **ignore** - `string | string[]` - *optional* - A glob pattern string or array of strings for files to be ignored. Defaults to `[]`.
132
+
- **urlPath** - `string` - *optional* - A base URL path to prepend to the resolved `files` entries.
133
+
- If the value starts with `./`, such as `'./static/'`, the component name will be included in the base url path
134
+
- If the value is `.`, then the component name will be the base url path
135
+
- Note: `..`is an invalid pattern and will result in an error
136
+
- Otherwise, the value here will be base url path. Leading and trailing `/` characters will be handled automatically (`/static/`, `/static`, and `static/` are all equivalent to `static`)
131
137
132
-
For example, to configure the [static](./built-in.md#static) component to server all files from `web` to the root URL path:
138
+
For example, to configure the [static](./built-in.md#static) component to serve all HTML files from the `web` source directory on the `static` URL endpoint:
133
139
134
140
```yaml
135
141
static:
136
-
files: 'web/**'
137
-
root: 'web'
142
+
files: 'web/*.html'
143
+
urlPath: 'static'
138
144
```
139
145
140
-
Or, to configure the [graphqlSchema](./built-in.md#graphqlschema) component to load all schemas within the `src/schema` directory:
146
+
If there are files such as `web/index.html` and `web/blog.html`, they would be available at `localhost/static/index.html` and `localhost/static/blog.html` respectively.
147
+
148
+
Furthermore, if the component is located in the `test-component` directory, and the `urlPath` was set to `'./static/'` instead, then the files would be served from `localhost/test-component/static/*` instead.
149
+
150
+
The `urlPath` is optional, for example to configure the [graphqlSchema](./built-in.md#graphqlschema) component to load all schemas within the `src/schema` directory, only specifying a `files` glob pattern is required:
141
151
142
152
```yaml
143
153
graphqlSchema:
144
154
files: 'src/schema/*.schema'
145
155
```
146
156
157
+
The `files` option also supports a more complex options object. These additional fields enable finer control of the glob pattern matching.
158
+
159
+
For example, to match files within `web`, and omit any within the `web/images` directory, the configuration could be:
160
+
```yaml
161
+
static:
162
+
files:
163
+
source: 'web/**/*'
164
+
ignore: 'web/images'
165
+
```
166
+
167
+
Or to disable matching directories within the glob pattern:
168
+
169
+
```yaml
170
+
test-component:
171
+
files:
172
+
source: 'dir/**/*'
173
+
onlyFiles: true
174
+
```
175
+
147
176
#### Resource Extension API
148
177
149
178
In order for an extension to be classified as a Resource Extension it must implement at least one of the `handleFile()`, `handleDirectory()`, `setupFile()`, or `setupDirectory()` methods. As a standalone extension, these methods should be named and exported directly. For example:
These methods are for processing directories. They can be async.
198
227
@@ -206,8 +235,8 @@ If the function returns or resolves a truthy value, then the component loading s
206
235
207
236
Parameters:
208
237
209
-
- **urlPath** - `string` - The recommended URL path of the file
210
-
- **path** - `string` - The relative path of the directory
238
+
- **urlPath** - `string` - The recommended URL path of the directory
239
+
- **absolutePath** - `string` - The absolute path of the directory
211
240
<!-- TODO: Replace the Object type here with a more specific type representing the resources argument of loadComponent() -->
212
241
- **resources** - `Object` - A collection of the currently loaded resources
213
242
@@ -219,14 +248,14 @@ A Protocol Extension is a more advanced form of a Resource Extension and is main
219
248
220
249
#### Protocol Extension Configuration
221
250
222
-
In addition to the `files`, `path`, and `root` [Resource Extension configuration](#resource-extension-configuration) options, and the `package` [Custom Component configuration](#custom-component-configuration) option, Protocol Extensions can also specify additional configuration options. Any options added to the extension configuration (in `config.yaml`), will be passed through to the `options` object of the `start()` and `startOnMainThread()` methods.
251
+
In addition to the `files`and `urlPath` [Resource Extension configuration](#resource-extension-configuration) options, and the `package` [Custom Component configuration](#custom-component-configuration) option, Protocol Extensions can also specify additional configuration options. Any options added to the extension configuration (in `config.yaml`), will be passed through to the `options` object of the `start()` and `startOnMainThread()` methods.
223
252
224
253
For example, the [Harper Next.js Extension](https://github.com/HarperDB/nextjs#options) specifies multiple option that can be included in its configuration. For example, a Next.js app using `@harperdb/nextjs` may specify the following `config.yaml`:
0 commit comments