Skip to content

Commit 01da14a

Browse files
committed
Merge branch 'main' into release_4.6
2 parents ed9ec84 + 543cf90 commit 01da14a

File tree

22 files changed

+987
-988
lines changed

22 files changed

+987
-988
lines changed

.gitbook.yaml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,11 @@ redirects:
7070
custom-functions: developers/applications/README.md
7171
custom-functions/define-routes: developers/applications/define-routes.md
7272
custom-functions/using-npm-git: developers/custom-functions/create-project.md
73-
custom-functions/custom-functions-operations: developers/components/operations.md
73+
custom-functions/custom-functions-operations: developers/operations-api/README.md
7474
custom-functions/debugging-custom-function: developers/applications/debugging.md
7575
custom-functions/example-projects: developers/applications/example-projects.md
76-
add-ons-and-sdks: developers/components/README.md
77-
add-ons-and-sdks/google-data-studio: developers/components/google-data-studio.md
76+
add-ons-and-sdks: developers/applications/README.md
77+
add-ons-and-sdks/google-data-studio: developers/miscellaneous/google-data-studio.md
7878
sql-guide: developers/sql-guide/README.md
7979
sql-guide/features-matrix: developers/sql-guide/features-matrix.md
8080
sql-guide/insert: developers/sql-guide/README.md

docs/SUMMARY.md

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,6 @@
1818
* [Define Fastify Routes](developers/applications/define-routes.md)
1919
* [Web Applications](developers/applications/web-applications.md)
2020
* [Example Projects](developers/applications/example-projects.md)
21-
* [Components](developers/components/README.md)
22-
* [Managing](developers/components/managing.md)
23-
* [Reference](developers/components/reference.md)
24-
* [Built-In Components](developers/components/built-in.md)
2521
* [REST](developers/rest.md)
2622
* [Operations API](developers/operations-api/README.md)
2723
* [Quick Start Examples](developers/operations-api/quickstart-examples.md)
@@ -117,17 +113,25 @@
117113
* [Reference](technical-details/reference/README.md)
118114
* [Analytics](technical-details/reference/analytics.md)
119115
* [Architecture](technical-details/reference/architecture.md)
116+
* [Blob](technical-details/reference/blob.md)
120117
* [Content Types](technical-details/reference/content-types.md)
118+
* [Components](technical-details/reference/components/README.md)
119+
* [Applications](technical-details/reference/components/applications.md)
120+
* [Built-In Extensions](technical-details/reference/components/built-in-extensions.md)
121+
* [Configuration](technical-details/reference/components/configuration.md)
122+
* [Extensions](technical-details/reference/components/extensions.md)
123+
* [(Experimental) Plugins](technical-details/reference/components/plugins.md)
121124
* [Data Types](technical-details/reference/data-types.md)
122125
* [Dynamic Schema](technical-details/reference/dynamic-schema.md)
123-
* [GraphQL](technical-details/reference/graphql.md)
124-
* [Harper Headers](technical-details/reference/headers.md)
125-
* [Harper Limits](technical-details/reference/limits.md)
126126
* [Globals](technical-details/reference/globals.md)
127-
* [Resource Class](technical-details/reference/resource.md)
128-
* [Transactions](technical-details/reference/transactions.md)
127+
* [GraphQL](technical-details/reference/graphql.md)
128+
* [Headers](technical-details/reference/headers.md)
129+
* [Limits](technical-details/reference/limits.md)
130+
* [Resources](technical-details/reference/resources/README.md)
131+
* [Migration](technical-details/reference/resources/migration.md)
132+
* [Instance Binding](technical-details/reference/resources/instance-binding.md)
129133
* [Storage Algorithm](technical-details/reference/storage-algorithm.md)
130-
* [Blob](technical-details/reference/blob.md)
134+
* [Transactions](technical-details/reference/transactions.md)
131135
* [Release Notes](technical-details/release-notes/README.md)
132136
* [Harper Tucker (Version 4)](technical-details/release-notes/4.tucker/README.md)
133137
* [4.6.0](technical-details/release-notes/4.tucker/4.6.0.md)

docs/deployments/configuration.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1180,7 +1180,7 @@ The name of the component. This will be used to name the folder where the compon
11801180

11811181
`package` - _Type_: string
11821182

1183-
A reference to your [component](../developers/components/managing.md#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here.
1183+
A reference to your [component](../technical-details/reference/components/applications.md#adding-components-to-root) package. This could be a remote git repo, a local folder/file or an NPM package. Harper will add this package to a package.json file and call `npm install` on it, so any reference that works with that paradigm will work here.
11841184

11851185
Read more about npm install [here](https://docs.npmjs.com/cli/v8/commands/npm-install)
11861186

docs/developers/applications/README.md

Lines changed: 65 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,81 @@
11
# Applications
22

3-
## Overview of HarperDB Applications
4-
53
Harper is more than a database, it's a distributed clustering platform allowing you to package your schema, endpoints and application logic and deploy them to an entire fleet of Harper instances optimized for on-the-edge scalable data delivery.
64

7-
In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper component, a fundamental building-block of the Harper ecosystem.
5+
In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper application, a fundamental building-block of the Harper ecosystem.
86

97
When working through this guide, we recommend you use the [Harper Application Template](https://github.com/HarperDB/application-template) repo as a reference.
108

11-
## Understanding the Component Application Architecture
9+
Before we get started, let's clarify some terminology that is used throughout the documentation.
10+
11+
**Components** are the high-level concept for modules that extend the Harper core platform adding additional functionality. The application you will build here is a component. In addition to applications, components also encompass extensions.
12+
13+
> We are actively working to disambiguate the terminology. When you see "component", such as in the Operations API or CLI, it generally refers to an application. We will do our best to clarify exactly which classification of a component whenever possible.
14+
15+
**Applications** are best defined as the implementation of a specific user-facing feature or functionality. Applications are built on top of extensions and can be thought of as the end product that users interact with. For example, a Next.js application that serves a web interface or an Apollo GraphQL server that provides a GraphQL API are both applications.
16+
17+
**Extensions** are the building blocks of the Harper component system. Applications depend on extensions to provide the functionality the application is implementing. For example, the built-in `graphqlSchema` extension enables applications to define their databases and tables using GraphQL schemas. Furthermore, the `@harperdb/nextjs` and `@harperdb/apollo` extensions are the building blocks that provide support for building Next.js and Apollo applications.
18+
19+
All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application.
1220

13-
Harper provides several types of components. Any package that is added to Harper is called a "component", and components are generally categorized as either "applications", which deliver a set of endpoints for users, or "extensions", which are building blocks for features like authentication, additional protocols, and connectors that can be used by other components. Components can be added to the `hdb/components` directory and will be loaded by Harper when it starts. Components that are remotely deployed to Harper (through the studio or the operation API) are installed into the `hdb/node_modules` directory. Using `harperdb run .` or `harperdb dev .` allows us to specifically load a certain application in addition to any that have been manually added to `hdb/components` or installed (in `hdb/node_modules`).
21+
Extensions can also depend on other extensions. For example, the [`@harperdb/apollo`](https://github.com/HarperDB/apollo) extension depends on the built-in `graphqlSchema` extension to create a cache table for Apollo queries. Applications can then use the `@harperdb/apollo` extension to implement an Apollo GraphQL backend server.
1422

1523
```mermaid
16-
flowchart LR
17-
Client(Client)-->Endpoints
18-
Client(Client)-->HTTP
19-
Client(Client)-->Extensions
20-
subgraph Harper
24+
flowchart TD
25+
subgraph Applications
2126
direction TB
22-
Applications(Applications)-- "Schemas" --> Tables[(Tables)]
23-
Applications-->Endpoints[/Custom Endpoints/]
24-
Applications-->Extensions
25-
Endpoints-->Tables
26-
HTTP[/REST/HTTP/]-->Tables
27-
Extensions[/Extensions/]-->Tables
27+
NextJSApp["Next.js App"]
28+
ApolloApp["Apollo App"]
29+
CustomResource["Custom Resource"]
30+
end
31+
32+
subgraph Extensions
33+
direction TB
34+
subgraph Custom
35+
NextjsExt["@harperdb/nextjs"]
36+
ApolloExt["@harperdb/apollo"]
37+
end
38+
subgraph Built-In
39+
GraphqlSchema["graphqlSchema"]
40+
JsResource["jsResource"]
41+
Rest["rest"]
2842
end
43+
end
44+
45+
subgraph Core
46+
direction TB
47+
Database["database"]
48+
FileSystem["file-system"]
49+
Networking["networking"]
50+
end
51+
52+
NextJSApp --> NextjsExt
53+
ApolloApp --> ApolloExt
54+
CustomResource --> JsResource & GraphqlSchema & Rest
55+
56+
NextjsExt --> Networking
57+
NextjsExt --> FileSystem
58+
ApolloExt --> GraphqlSchema
59+
ApolloExt --> Networking
60+
61+
GraphqlSchema --> Database
62+
JsResource --> Database
63+
Rest --> Networking
64+
2965
```
3066

67+
> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleComponent` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../../technical-details/reference/components/plugins.md) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported.
68+
69+
Beyond applications and extensions, components are further classified as built-in or custom. **Built-in** components are included with Harper by default and can be directly referenced by their name. The `graphqlSchema`, `rest`, and `jsResource` extensions used in the previous application example are all examples of built-in extensions. **Custom** components must use external references, generally npm or GitHub packages, and are often included as dependencies within the `package.json` of the component.
70+
71+
> Harper maintains a number of custom components that are available on `npm` and `GitHub`, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) extension or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application.
72+
73+
Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../../technical-details/reference/components/built-in.md) documentation page, and the list of custom extensions and applications is available below.
74+
75+
This guide is going to walk you through building a basic Harper application using a set of built-in extensions.
76+
77+
> The Technical Details section of the documentation contains a [complete reference for all aspects of components](../../technical-details/reference/components), applications, extensions, and more.
78+
3179
## Custom Functionality with JavaScript
3280

3381
[The getting started guide](../../getting-started/first-harper-app.md) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resource.md), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class.
@@ -163,16 +211,7 @@ Harper provides a powerful JavaScript API with significant capabilities that go
163211
164212
## Configuring Applications/Components
165213
166-
Every application or component can define their own configuration in a `config.yaml`. If you are using the application template, you will have a [default configuration in this config file](https://github.com/HarperDB/application-template/blob/main/config.yaml) (which is default configuration if no config file is provided). Within the config file, you can configure how different files and resources are loaded and handled. The default configuration file itself is documented with directions. Each entry can specify any `files` that the loader will handle, and can also optionally specify what, if any, URL `path`s it will handle. A path of `/` means that the root URLs are handled by the loader, and a path of `.` indicates that the URLs that start with this application's name are handled.
167-
168-
This config file allows you define a location for static files, as well (that are directly delivered as-is for incoming HTTP requests).
169-
170-
Each configuration entry can have the following properties, in addition to properties that may be specific to the individual component:
171-
172-
* `files`: This specifies the set of files that should be handled the component. This is a glob pattern, so a set of files can be specified like "directory/\*\*".
173-
* `path`: This is the URL path that is handled by this component.
174-
* `root`: This specifies the root directory for mapping file paths to the URLs. For example, if you want all the files in `web/**` to be available in the root URL path via the static handler, you could specify a root of `web`, to indicate that the web directory maps to the root URL path.
175-
* `package`: This is used to specify that this component is a third party package, and can be loaded from the specified package reference (which can be an NPM package, Github reference, URL, etc.).
214+
For complete information of configuring applications, refer to the [Component Configuration](../../technical-details/reference/components/configuration.md) reference page.
176215
177216
## Define Fastify Routes
178217

docs/developers/components/README.md

Lines changed: 0 additions & 22 deletions
This file was deleted.

0 commit comments

Comments
 (0)