Reference
Last updated
Last updated
The technical definition of a Harper component is fairly loose. In the absolute, simplest form, a component is any JavaScript module that is compatible with the . For example, a module with a singular resources.js
file is technically a valid component.
Harper provides many features as built-in components, these can be used directly without installing any other dependencies.
Other features are provided by custom components. These can be npm packages such as and (which are maintained by Harper), or something maintained by the community. Custom components follow the same configuration rules and use the same APIs that Harper's built-in components do. The only difference is that they must be apart of the component's dependencies.
Documentation is available for all and Harper components.
Harper components are configured with a config.yaml
file located in the root of the component module directory. This file is how a component configures other components it depends on. Each entry in the file starts with a component name, and then configuration values are indented below it.
It is the entry's name
that is used for component resolution. It can be one of the , or it must match a package dependency of the component as specified by package.json
. The section provides more details and examples.
For some built-in components they can be configured with as little as a top-level boolean; for example, the extension can be enabled with just:
Other components (built-in or custom), will generally have more configuration options. Some options are ubiquitous to the Harper platform, such as the files
, path
, and root
options for a , or package
for a . Additionally, can be defined for .
Any custom component must be configured with the package
option in order for Harper to load that component. When enabled, the name of package must match a dependency of the component. For example, to use the @harperdb/nextjs
extension, it must first be included in package.json
:
Then, within config.yaml
it can be enabled and configured using:
And now in config.yaml
:
Harper components do not need to specify a config.yaml
. Harper uses the following default configuration to load components.
If a config.yaml
is defined, it will not be merged with the default config.
There are two key types of Harper Extensions: Resource Extension and Protocol Extensions. The key difference is a Protocol Extensions can return a Resource Extension.
Functionally, what makes an extension a component is the contents of config.yaml
. Unlike the Application Template referenced earlier, which specified multiple components within the config.yaml
, an extension will specify an extensionModule
option.
extensionModule - string
- required - A path to the extension module source code. The path must resolve from the root of the extension module directory.
If the extension is being written in something other than JavaScript (such as TypeScript), ensure that the path resolves to the built version, (i.e. extensionModule: ./dist/index.js
)
Keep in mind that the CLI command
harperdb restart
or CLI argumentrestart=true
only restarts the worker threads. If a component is deployed usingharperdb deploy
, the code within thesetupFile()
andsetupDirectory()
methods will not be executed until the system is completely shutdown and turned back on.
Other than their execution behavior, the handleFile()
and setupFile()
methods, and handleDirectory()
and setupDirectory()
methods have identical function definitions (arguments and return value behavior).
files - string
- required - Specifies the set of files and directories that should be handled by the component. Can be a glob pattern.
path - string
- optional - Specifies the URL path to be handled by the component.
root - string
- optional - Specifies the root directory for mapping file paths to the URLs.
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:
handleFile(contents, urlPath, path, resources): void | Promise<void>
setupFile(contents, urlPath, path, resources): void | Promise<void>
These methods are for processing individual files. They can be async.
Remember!
setupFile()
is executed once on the main thread during the main start sequence.
handleFile()
is executed on worker threads and is executed again during restarts.
Parameters:
contents - Buffer
- The contents of the file
urlPath - string
- The recommended URL path of the file
path - string
- The relative path of the file
resources - Object
- A collection of the currently loaded resources
Returns: void | Promise<void>
handleDirectory(urlPath, path, resources): boolean | void | Promise<boolean | void>
setupDirectory(urlPath, path, resources): boolean | void | Promise<boolean | void>
These methods are for processing directories. They can be async.
If the function returns or resolves a truthy value, then the component loading sequence will end and no other entries within the directory will be processed.
Remember!
setupFile()
is executed once on the main thread during the main start sequence.
handleFile()
is executed on worker threads and is executed again during restarts.
Parameters:
urlPath - string
- The recommended URL path of the file
path - string
- The relative path of the directory
resources - Object
- A collection of the currently loaded resources
Returns: boolean | void | Promise<boolean | void>
start(options): ResourceExtension | Promise<ResourceExtension>
startOnMainThread(options): ResourceExtension | Promise<ResourceExtension>
Parameters:
options - Object
- An object representation of the extension's configuration options.
Since npm allows for a , this can be used to create custom references. For example, to depend on a specific GitHub branch, first update the package.json
:
Refer to the documentation for more information on these fields.
A Harper Extension is a extensible component that is intended to be used by other components. The built-in components and are both examples of extensions.
For example, the config.yaml
specifies extensionModule: ./extension.js
.
It is also recommended that all extensions have a package.json
that specifies JavaScript package metadata such as name, version, type, etc. Since extensions are just JavaScript packages, they can do anything a JavaScript package can normally do. It can be written in TypeScript, and compiled to JavaScript. It can export an executable (using the property). It can be published to npm. The possibilities are endless!
Furthermore, what defines an extension separately from a component is that it leverages any of the or APIs. The key is in the name, extensions are extensible.
A Resource Extension is for processing a certain type of file or directory. For example, the built-in extension handles executing JavaScript files.
Resource Extensions are comprised of four distinct function exports, , , , and . 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.
Any 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.
For example, to configure the component to server all files from web
to the root URL path:
Or, to configure the component to load all schemas within the src/schema
directory:
When returned by a , these methods should be defined on the object instead:
A Protocol Extension is a more advanced form of a Resource Extension and is mainly used for implementing higher level protocols. For example, the handles building and running a Next.js project. A Protocol Extension is particularly useful for adding custom networking handlers (see the global API documentation for more information).
In addition to the files
, path
, and root
options, and the package
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.
For example, the 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
:
Many protocol extensions will use the port
and securePort
options for configuring networking handlers. Many of the global APIs accept port
and securePort
options, so components replicated this for simpler pass-through.
A Protocol Extension is made up of two distinct methods, and . Similar to a Resource Extension, the start()
method is executed on all worker threads, and executed again on restarts. The startOnMainThread()
method is only executed once during the initial system start sequence. These methods have identical options
object parameter, and can both return a Resource Extension (i.e. an object containing one or more of the methods listed above).
Returns: Object
- An object that implements any of the