@harperfast/template-vue-studio 1.13.6 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
- package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/.agents/skills/harper-mcp/AGENTS.md +228 -155
- package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
- package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/agent/skills/harper-mcp/AGENTS.md +228 -155
- package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/package.json +1 -1
- package/skills-lock.json +7 -7
|
@@ -9,37 +9,43 @@ metadata:
|
|
|
9
9
|
- reference/v5/database/schema.md#Overview
|
|
10
10
|
- reference/v5/database/schema.md#Type Directives
|
|
11
11
|
- reference/v5/database/schema.md#Field Directives
|
|
12
|
-
sourceCommit:
|
|
13
|
-
inputHash:
|
|
12
|
+
sourceCommit: e4a7bd899e1a68a83d9ed1d770ec73569fabc260
|
|
13
|
+
inputHash: 16a9e0488c853439
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
# Schema Design and GraphQL Tooling
|
|
17
17
|
|
|
18
|
-
Instructions for the agent to follow when designing Harper schemas,
|
|
18
|
+
Instructions for the agent to follow when designing Harper database schemas using GraphQL type definitions, core directives, and tooling configuration.
|
|
19
19
|
|
|
20
20
|
## When to Use
|
|
21
21
|
|
|
22
|
-
Apply this rule when creating or modifying Harper schema files, configuring `graphqlSchema` in `config.yaml
|
|
22
|
+
Apply this rule when creating or modifying Harper schema files — defining tables, primary keys, indexes, and export behavior. Use it when configuring `graphqlSchema` in `config.yaml` or when choosing directives to control table structure, access patterns, and record lifecycle.
|
|
23
23
|
|
|
24
24
|
## How It Works
|
|
25
25
|
|
|
26
|
-
1. **
|
|
26
|
+
1. **Create a schema file** using standard GraphQL type definitions with Harper-specific directives. Name it (e.g., `schema.graphql`) and place it in your component directory.
|
|
27
|
+
|
|
28
|
+
```graphql
|
|
29
|
+
type Dog @table {
|
|
30
|
+
id: Long @primaryKey
|
|
31
|
+
name: String
|
|
32
|
+
breed: String
|
|
33
|
+
age: Int
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
2. **Register the schema** in the component's `config.yaml` using the `graphqlSchema` plugin:
|
|
27
38
|
|
|
28
39
|
```yaml
|
|
29
40
|
graphqlSchema:
|
|
30
41
|
files: 'schema.graphql'
|
|
31
42
|
```
|
|
32
43
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
2. **Mark tables with `@table`**: Apply `@table` to every GraphQL type that should become a Harper database table. The type name becomes the table name by default.
|
|
44
|
+
3. **Mark every table type with `@table`**. This tells Harper to create and manage the table. The type name becomes the table name by default.
|
|
36
45
|
|
|
37
46
|
```graphql
|
|
38
|
-
type
|
|
47
|
+
type MyTable @table {
|
|
39
48
|
id: Long @primaryKey
|
|
40
|
-
name: String
|
|
41
|
-
breed: String
|
|
42
|
-
age: Int
|
|
43
49
|
}
|
|
44
50
|
```
|
|
45
51
|
|
|
@@ -53,13 +59,15 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
53
59
|
| `eviction` | `Int` | `0` | Additional seconds after `expiration` before physical removal |
|
|
54
60
|
| `scanInterval` | `Int` | `(expiration + eviction) / 4` | Seconds between eviction scans |
|
|
55
61
|
| `replicate` | `Boolean` | `true` | Enable replication of this table |
|
|
56
|
-
| `replicaExpiration` | `Float` | `3600` | Seconds
|
|
62
|
+
| `replicaExpiration` | `Float` | `3600` | Seconds to keep a local residency replica |
|
|
57
63
|
| `replicaRefreshFraction` | `Float` | `0.5` | Fraction of `replicaExpiration` after which a read renews the replica lifetime |
|
|
58
64
|
| `audit` | `Boolean` | `logging.auditLog` | Enable the table's transaction log |
|
|
59
65
|
| `cacheControl` | `String` | — | `Cache-Control` header for anonymous GET/HEAD 200/304 responses |
|
|
60
66
|
| `randomAccessFields` | `Boolean` | `storage.randomAccessFields` | Pin this table's record encoding |
|
|
61
67
|
|
|
62
|
-
|
|
68
|
+
4. **Designate a primary key with `@primaryKey`** on exactly one field per table. Primary keys must be unique; duplicate inserts are rejected. If no primary key is provided on insert, Harper auto-generates one:
|
|
69
|
+
- `String` or `ID` → UUID string
|
|
70
|
+
- `Int`, `Long`, or `Any` → auto-incrementing integer
|
|
63
71
|
|
|
64
72
|
```graphql
|
|
65
73
|
type Product @table {
|
|
@@ -68,13 +76,9 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
68
76
|
}
|
|
69
77
|
```
|
|
70
78
|
|
|
71
|
-
|
|
72
|
-
- **UUID string** — when type is `String` or `ID`
|
|
73
|
-
- **Auto-incrementing integer** — when type is `Int`, `Long`, or `Any`
|
|
74
|
-
|
|
75
|
-
Prefer `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
|
|
79
|
+
Use `Long` or `Any` for auto-generated numeric keys; `Int` is 32-bit and may be insufficient for large tables.
|
|
76
80
|
|
|
77
|
-
|
|
81
|
+
5. **Add `@indexed` to fields that need fast querying**. Required for filtering by an attribute in REST queries, SQL, or NoSQL operations. If the field value is an array, each element is individually indexed.
|
|
78
82
|
|
|
79
83
|
```graphql
|
|
80
84
|
type Product @table {
|
|
@@ -84,9 +88,7 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
84
88
|
}
|
|
85
89
|
```
|
|
86
90
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
5. **Expose tables externally with `@export`**: Apply `@export` to make a table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment.
|
|
91
|
+
6. **Expose the table externally with `@export`**. This makes the table accessible via REST, MQTT, and other interfaces. The optional `name` parameter sets the URL path segment; without it, the type name is used.
|
|
90
92
|
|
|
91
93
|
```graphql
|
|
92
94
|
type MyTable @table @export(name: "my-table") {
|
|
@@ -94,9 +96,9 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
94
96
|
}
|
|
95
97
|
```
|
|
96
98
|
|
|
97
|
-
`@export` alone does not serve HTTP traffic — REST must also be enabled for the application
|
|
99
|
+
`@export` alone does not serve HTTP traffic — REST must also be enabled for the application, either with `rest: true` in `config.yaml` or by Harper's built-in default for a component with no configuration file.
|
|
98
100
|
|
|
99
|
-
|
|
101
|
+
7. **Use `@sealed` to prevent extra properties** on records beyond those declared in the schema. By default, Harper allows records to have additional properties.
|
|
100
102
|
|
|
101
103
|
```graphql
|
|
102
104
|
type StrictRecord @table @sealed {
|
|
@@ -105,33 +107,13 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
105
107
|
}
|
|
106
108
|
```
|
|
107
109
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
- `@
|
|
112
|
-
- `@updatedTime` — auto-assigns a Unix epoch millisecond timestamp on each update.
|
|
113
|
-
- `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); overrides the table-level `expiration` default.
|
|
114
|
-
- `@hidden` — suppresses the type or field from MCP tool descriptors and the OpenAPI document. Does not restrict data access.
|
|
115
|
-
|
|
116
|
-
```graphql
|
|
117
|
-
type Event @table {
|
|
118
|
-
id: Long @primaryKey
|
|
119
|
-
createdAt: Long @createdTime
|
|
120
|
-
updatedAt: Long @updatedTime
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
type Session @table {
|
|
124
|
-
id: ID @primaryKey
|
|
125
|
-
token: String
|
|
126
|
-
expiresAt: Long @expiresAt
|
|
127
|
-
}
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Key `@expiresAt` behaviors:
|
|
131
|
-
- Takes an absolute Unix epoch millisecond timestamp, not a duration. A full-record `put` that omits the field clears it; a `patch` preserves it.
|
|
132
|
-
- A per-record value may extend or shorten a record's expiration relative to the table-level `expiration` default. When a record omits the field, the table default (if any) applies.
|
|
110
|
+
8. **Use timestamp directives** to auto-populate lifecycle fields:
|
|
111
|
+
- `@createdTime` — assigns Unix epoch milliseconds on record creation
|
|
112
|
+
- `@updatedTime` — assigns Unix epoch milliseconds on every update
|
|
113
|
+
- `@expiresAt` — marks a field as the record's absolute expiration time (Unix epoch milliseconds); authoritative over the table-level `expiration` default
|
|
133
114
|
|
|
134
115
|
9. **Use `@embed`** to automatically compute an embedding vector for an attribute whenever the source field is written (requires `source` and `model` arguments; field type must be `[Float]`):
|
|
116
|
+
|
|
135
117
|
```graphql
|
|
136
118
|
type Document @table {
|
|
137
119
|
id: Long @primaryKey
|
|
@@ -139,11 +121,12 @@ Apply this rule when creating or modifying Harper schema files, configuring `gra
|
|
|
139
121
|
embedding: [Float] @embed(source: "text", model: "default")
|
|
140
122
|
}
|
|
141
123
|
```
|
|
142
|
-
|
|
124
|
+
|
|
125
|
+
10. **Use unique `database` names** in plugins or applications to avoid table naming collisions, since all tables default to the `data` database.
|
|
143
126
|
|
|
144
127
|
## Examples
|
|
145
128
|
|
|
146
|
-
**Minimal
|
|
129
|
+
**Minimal two-table schema:**
|
|
147
130
|
|
|
148
131
|
```graphql
|
|
149
132
|
type Dog @table {
|
|
@@ -159,7 +142,17 @@ type Breed @table {
|
|
|
159
142
|
}
|
|
160
143
|
```
|
|
161
144
|
|
|
162
|
-
**
|
|
145
|
+
**Table with name override and specific database:**
|
|
146
|
+
|
|
147
|
+
```graphql
|
|
148
|
+
type Product @table(table: "products", database: "commerce") {
|
|
149
|
+
id: Long @primaryKey
|
|
150
|
+
name: String @indexed
|
|
151
|
+
price: Float @indexed
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**Caching table with expiration and eviction tuning:**
|
|
163
156
|
|
|
164
157
|
```graphql
|
|
165
158
|
# Expire after 5 minutes, evict after 1 hour, scan every 10 minutes
|
|
@@ -179,16 +172,7 @@ type Product @table(cacheControl: "public, max-age=60") @export {
|
|
|
179
172
|
}
|
|
180
173
|
```
|
|
181
174
|
|
|
182
|
-
**Table
|
|
183
|
-
|
|
184
|
-
```graphql
|
|
185
|
-
type Event @table(database: "analytics", expiration: 86400) {
|
|
186
|
-
id: Long @primaryKey
|
|
187
|
-
name: String @indexed
|
|
188
|
-
}
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
**Replica lifetime tuning:**
|
|
175
|
+
**Table with replica lifetime control:**
|
|
192
176
|
|
|
193
177
|
```graphql
|
|
194
178
|
# Keep fetched records for a day; a read after six hours renews them
|
|
@@ -198,18 +182,19 @@ type Order @table(replicaExpiration: 86400, replicaRefreshFraction: 0.25) {
|
|
|
198
182
|
}
|
|
199
183
|
```
|
|
200
184
|
|
|
201
|
-
**
|
|
185
|
+
**Session table with per-record expiration and timestamps:**
|
|
202
186
|
|
|
203
187
|
```graphql
|
|
204
|
-
type
|
|
188
|
+
type Session @table {
|
|
205
189
|
id: ID @primaryKey
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
190
|
+
userId: String @indexed
|
|
191
|
+
createdAt: Long @createdTime
|
|
192
|
+
updatedAt: Long @updatedTime
|
|
193
|
+
expiresAt: Long @expiresAt
|
|
209
194
|
}
|
|
210
195
|
```
|
|
211
196
|
|
|
212
|
-
**`config.yaml`
|
|
197
|
+
**`config.yaml` registration:**
|
|
213
198
|
|
|
214
199
|
```yaml
|
|
215
200
|
graphqlSchema:
|
|
@@ -218,12 +203,10 @@ graphqlSchema:
|
|
|
218
203
|
|
|
219
204
|
## Notes
|
|
220
205
|
|
|
221
|
-
-
|
|
222
|
-
- `@
|
|
223
|
-
-
|
|
224
|
-
- `
|
|
225
|
-
-
|
|
226
|
-
- `replicaExpiration` and `
|
|
206
|
+
- `@export` is a routing directive, not access control. Omitting it returns 404 to callers but does not protect the data — the table remains accessible through the Operations API and SQL. Use RBAC role grants and `attribute_permissions` for actual access control.
|
|
207
|
+
- `@hidden` (on types or fields) suppresses entries from MCP tool descriptors and the OpenAPI document only. It does not restrict data access. Use `attribute_permissions` on roles for field-level enforcement.
|
|
208
|
+
- Null values are indexed by default for `@indexed` fields, enabling queries like `GET /Product/?category=null`. This matches records that store `null`, not records that omit the attribute.
|
|
209
|
+
- `cacheControl` emits the header only on anonymous (unauthenticated) GET/HEAD 200/304 responses. Authenticated responses receive `Cache-Control: private, no-cache` regardless of the declaration.
|
|
210
|
+
- A `patch` of other fields preserves an existing `@expiresAt` value; a full `put` that omits the field clears it. Always re-include `expiresAt` in session-renewal writes.
|
|
211
|
+
- `replicaExpiration` and `randomAccessFields` apply to RocksDB only. LMDB tables ignore replica behavior regardless of settings.
|
|
227
212
|
- Disabling replication on a table (`replicate: false`) and re-enabling it later will not catch up on writes made while replication was disabled.
|
|
228
|
-
- `randomAccessFields` on `@table` pins the encoding when the table is created. Editing the argument later does not repin an existing table.
|
|
229
|
-
- `@hidden` is a metadata-visibility directive only — it does not restrict data access. Use `attribute_permissions` on roles for field-level access control.
|
|
@@ -7,17 +7,17 @@ metadata:
|
|
|
7
7
|
mode: generate
|
|
8
8
|
sources:
|
|
9
9
|
- release-notes/v5-lincoln/v5-migration.md
|
|
10
|
-
sourceCommit:
|
|
11
|
-
inputHash:
|
|
10
|
+
sourceCommit: 62139d5475bb9993c3aa6bc8d23420ea7610f739
|
|
11
|
+
inputHash: 141693224b082d1c
|
|
12
12
|
---
|
|
13
13
|
|
|
14
14
|
# v5 Upgrade: Breaking Changes and Migration Guide
|
|
15
15
|
|
|
16
|
-
Instructions for the agent to
|
|
16
|
+
Instructions for the agent to apply when migrating a Harper application to v5, covering all breaking changes and required code updates.
|
|
17
17
|
|
|
18
18
|
## When to Use
|
|
19
19
|
|
|
20
|
-
Apply this rule when upgrading an existing Harper application from v4 to v5, when encountering runtime errors
|
|
20
|
+
Apply this rule when upgrading an existing Harper application from v4 to v5, when encountering runtime errors related to module loading, transactions, record access, or process spawning after a v5 upgrade, or when scaffolding new v5-compatible application code.
|
|
21
21
|
|
|
22
22
|
## How It Works
|
|
23
23
|
|
|
@@ -27,12 +27,12 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
|
|
|
27
27
|
import { tables } from 'harper';
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
2. **Enable install scripts if needed**: Harper v5 runs `npm install` with `--ignore-scripts` by default. If your application requires install scripts (e.g., to
|
|
30
|
+
2. **Enable install scripts if needed**: Harper v5 runs `npm install` with `--ignore-scripts` by default. If your application requires install scripts (e.g., to install native binaries), set `allowInstallScripts` in your deployment options.
|
|
31
31
|
|
|
32
|
-
3. **Update `Table.get` usage**: `Table.get` now returns a plain frozen record object, not a table class instance. The `wasLoadedFromSource()` method no longer exists on the returned
|
|
32
|
+
3. **Update `Table.get` usage**: `Table.get` now returns a plain frozen record object, not a table class instance. The `wasLoadedFromSource()` method no longer exists on the returned record. Use a `RequestTarget` and check `loadedFromSource` on the target instead.
|
|
33
33
|
|
|
34
34
|
```javascript
|
|
35
|
-
// Before
|
|
35
|
+
// Before (v4):
|
|
36
36
|
const record = await Table.get(id);
|
|
37
37
|
if (record.wasLoadedFromSource()) {
|
|
38
38
|
// record was loaded from origin (not cache)
|
|
@@ -40,8 +40,7 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
|
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
```javascript
|
|
43
|
-
// After
|
|
44
|
-
import { getContext } from 'harper';
|
|
43
|
+
// After (v5):
|
|
45
44
|
const target = new RequestTarget();
|
|
46
45
|
target.id = id;
|
|
47
46
|
const record = await Table.get(target);
|
|
@@ -50,34 +49,23 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
|
|
|
50
49
|
}
|
|
51
50
|
```
|
|
52
51
|
|
|
53
|
-
The record objects
|
|
52
|
+
The record objects still expose `getUpdatedTime` and `getExpiresAt` methods.
|
|
54
53
|
|
|
55
|
-
4. **Handle frozen records**:
|
|
54
|
+
4. **Handle frozen records**: Records returned by `Table.get` are frozen — you cannot mutate them directly. Spread into a new object instead.
|
|
56
55
|
|
|
57
56
|
```javascript
|
|
58
|
-
// Before
|
|
57
|
+
// Before (v4):
|
|
59
58
|
const record = await Table.get(id);
|
|
60
59
|
record.property = 'changed';
|
|
61
60
|
```
|
|
62
61
|
|
|
63
62
|
```javascript
|
|
64
|
-
// After
|
|
63
|
+
// After (v5):
|
|
65
64
|
let record = await Table.get(id);
|
|
66
65
|
record = { ...record, property: 'changed' };
|
|
67
66
|
```
|
|
68
67
|
|
|
69
|
-
5. **
|
|
70
|
-
|
|
71
|
-
```yaml
|
|
72
|
-
applications:
|
|
73
|
-
allowedSpawnCommands:
|
|
74
|
-
- npm
|
|
75
|
-
- node
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
Additionally, `spawn`, `execFile`, and `fork` now require a `name` property in the `options` argument to prevent process multiplication across threads.
|
|
79
|
-
|
|
80
|
-
6. **Update transaction and context usage**: Harper v5 uses asynchronous context tracking. `Table.get` and other calls now automatically inherit the current transaction. Code that previously omitted context to bypass a transaction will no longer work as expected. Explicitly commit the transaction or wrap calls in a new transaction to read updated data:
|
|
68
|
+
5. **Update transaction and context usage**: Harper v5 uses asynchronous context tracking. `Table.get` and other table calls now automatically inherit the current transaction. If your code previously omitted context to bypass a transaction and read the latest data, that workaround no longer works. Explicitly commit the transaction and/or wrap reads in a new transaction using `getContext` and `transaction` from `'harper'`.
|
|
81
69
|
|
|
82
70
|
```javascript
|
|
83
71
|
import { setTimeout as delay } from 'node:timers/promises';
|
|
@@ -94,47 +82,45 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
|
|
|
94
82
|
}
|
|
95
83
|
```
|
|
96
84
|
|
|
97
|
-
|
|
85
|
+
6. **Register allowed spawn commands**: Spawning child processes via `node:child_process` is now restricted. Only executables listed in `applications.allowedSpawnCommands` in `harper-config.yaml` may be spawned. Additionally, `spawn`, `execFile`, and `fork` require a `name` property in the `options` argument to prevent process multiplication across threads. `exec` is not usable through the substituted module, and `execSync` always throws.
|
|
98
86
|
|
|
99
|
-
|
|
87
|
+
```yaml
|
|
88
|
+
applications:
|
|
89
|
+
allowedSpawnCommands:
|
|
90
|
+
- npm
|
|
91
|
+
- node
|
|
92
|
+
```
|
|
100
93
|
|
|
101
|
-
|
|
94
|
+
7. **Replace `blob.save()`**: The `blob.save()` method has been removed. Use the `saveBeforeCommit` flag in the options passed to the `Blob` constructor instead.
|
|
102
95
|
|
|
103
|
-
|
|
96
|
+
8. **Configure the module loader**: Harper v5 loads application modules through Node.js's VM module API. The default mode is `vm-current-context`, which shares JavaScript intrinsics (`Object`, `Array`, `Promise`, etc.) with Harper to avoid `instanceof` and identity-check failures across the application/Harper boundary.
|
|
104
97
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
98
|
+
```yaml
|
|
99
|
+
applications:
|
|
100
|
+
lockdown: seal-after-load
|
|
101
|
+
moduleLoader: vm-current-context # vm-current-context (default) | vm | native | compartment
|
|
102
|
+
dependencyLoader: auto # auto (default) | app | native
|
|
103
|
+
allowedDirectory: app # app (default) | any
|
|
104
|
+
```
|
|
111
105
|
|
|
112
|
-
|
|
106
|
+
- Use `vm` only if you need separate per-application intrinsics.
|
|
107
|
+
- Use `native` to restore pre-v5 behavior (standard `import()`), but note that application-specific context (tagged `logger`, per-app `config`) will not be available.
|
|
108
|
+
- Use `dependencyLoader: native` to apply native loading only to npm packages while keeping the VM loader for first-party source files.
|
|
113
109
|
|
|
114
|
-
|
|
110
|
+
9. **Configure `lockdown`**: The default `lockdown: seal-after-load` seals intrinsic prototypes (`Object`, `Array`, `Promise`, `Map`, `Set`, and others) after all components load, blocking prototype pollution. Before v5.4.0 the default was `freeze-after-load`, which froze the intrinsics instead. If a dependency mutates an intrinsic prototype at runtime and throws a `TypeError`, set `lockdown: none` as a temporary workaround.
|
|
115
111
|
|
|
116
112
|
```yaml
|
|
117
113
|
applications:
|
|
118
|
-
|
|
114
|
+
lockdown: seal-after-load
|
|
119
115
|
```
|
|
120
116
|
|
|
121
|
-
|
|
117
|
+
An in-place upgrade from v4 retains the existing config file, which has no `lockdown` value — Harper will not lock intrinsics until you explicitly add the key.
|
|
122
118
|
|
|
123
|
-
|
|
119
|
+
10. **Check `allowedDirectory` in production**: In production, `allowedDirectory: app` is the default, restricting module loading to the application's own directory tree. If your application loads modules from outside its directory, set `allowedDirectory: any`. This restriction does not apply in dev mode.
|
|
124
120
|
|
|
125
|
-
|
|
121
|
+
11. **Update response objects**: If a REST method returns an object with a `headers` property, Harper v5 will use it as the response headers. Ensure any object with a `headers` property returned from a REST method is intentional.
|
|
126
122
|
|
|
127
|
-
|
|
128
|
-
applications:
|
|
129
|
-
lockdown: none
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
11. **Check `allowedDirectory` in production**: In production, applications can only load modules from within their own directory tree (`allowedDirectory: app`). If your application loads files from outside its directory, set:
|
|
133
|
-
|
|
134
|
-
```yaml
|
|
135
|
-
applications:
|
|
136
|
-
allowedDirectory: any
|
|
137
|
-
```
|
|
123
|
+
12. **Use `getContext` instead of passing context explicitly**: Context no longer needs to be threaded through every call. Access it via `getContext` exported from `'harper'`. Prefer `static` methods on Resources/Tables for endpoints and access request information from the `target` argument or via `getContext`.
|
|
138
124
|
|
|
139
125
|
## Examples
|
|
140
126
|
|
|
@@ -142,7 +128,7 @@ Apply this rule when upgrading an existing Harper application from v4 to v5, whe
|
|
|
142
128
|
|
|
143
129
|
```yaml
|
|
144
130
|
applications:
|
|
145
|
-
lockdown:
|
|
131
|
+
lockdown: seal-after-load
|
|
146
132
|
moduleLoader: vm-current-context
|
|
147
133
|
dependencyLoader: auto
|
|
148
134
|
allowedDirectory: app
|
|
@@ -151,15 +137,18 @@ applications:
|
|
|
151
137
|
- node
|
|
152
138
|
```
|
|
153
139
|
|
|
154
|
-
###
|
|
140
|
+
### Disabling the VM loader entirely
|
|
155
141
|
|
|
156
|
-
```
|
|
157
|
-
|
|
142
|
+
```yaml
|
|
143
|
+
applications:
|
|
144
|
+
moduleLoader: native
|
|
158
145
|
```
|
|
159
146
|
|
|
160
|
-
### Checking `loadedFromSource`
|
|
147
|
+
### Checking `loadedFromSource` and using `getContext`
|
|
161
148
|
|
|
162
149
|
```javascript
|
|
150
|
+
import { getContext, transaction } from 'harper';
|
|
151
|
+
|
|
163
152
|
const target = new RequestTarget();
|
|
164
153
|
target.id = id;
|
|
165
154
|
const record = await Table.get(target);
|
|
@@ -168,7 +157,7 @@ if (target.loadedFromSource) {
|
|
|
168
157
|
}
|
|
169
158
|
```
|
|
170
159
|
|
|
171
|
-
###
|
|
160
|
+
### Spreading a frozen record
|
|
172
161
|
|
|
173
162
|
```javascript
|
|
174
163
|
let record = await Table.get(id);
|
|
@@ -177,8 +166,8 @@ record = { ...record, property: 'changed' };
|
|
|
177
166
|
|
|
178
167
|
## Notes
|
|
179
168
|
|
|
180
|
-
- The `logger` exported from `'harper'` is tagged with the application name when using the VM module loader. It is not available
|
|
181
|
-
- `instanceof` checks for values crossing the application/Harper boundary will fail when using `moduleLoader: vm` (separate intrinsics). Use `vm-current-context` (the default) to avoid this.
|
|
182
|
-
- `import()` behavior depends on the `moduleLoader
|
|
183
|
-
-
|
|
184
|
-
-
|
|
169
|
+
- The `logger` exported from `'harper'` is tagged with the application name when using the VM module loader. It is not available with `moduleLoader: native`.
|
|
170
|
+
- `instanceof` checks for values crossing the application/Harper boundary will fail when using `moduleLoader: vm` (separate intrinsics). Use `moduleLoader: vm-current-context` (the default) to avoid this.
|
|
171
|
+
- `import()` behavior depends on the selected `moduleLoader`. With `native`, it behaves as standard Node.js `import()` with no application context.
|
|
172
|
+
- The `exec` function from `node:child_process` is not usable through the substituted module in v5; `execSync` always throws.
|
|
173
|
+
- Record objects returned by `Table.get` expose `getUpdatedTime` and `getExpiresAt` even though they are frozen plain objects.
|