Harper Resources
Overview
A Resource is a class that provides a unified interface for a set of records or
entities. Resources are how you add custom server-side behavior to a Harper app.
They are loaded by the jsResource extension (default file resources.js) and,
when exported, become live REST and GraphQL endpoints.
A resource either extends a database table (to customize an existing table's
behavior) or extends the base Resource class (to expose data from anywhere —
an external API, a computed view, an in-memory source).
Method → HTTP verb mapping
The Resource API mirrors REST. Override the method matching the operation you want to customize:
| Method | HTTP | Use |
|---|---|---|
get(target) |
GET | Retrieve a record/collection |
post(data) |
POST | Create |
put(target, data) |
PUT | Replace |
patch(target, data) |
PATCH | Partial update |
delete(target) |
DELETE | Remove |
search(query) |
GET (query) | Query with conditions |
subscribe / publish |
MQTT/WebSocket | Real-time |
Extending a table
Add computed fields or guard logic while keeping the table's built-in behavior via
super:
export class MyTable extends tables.MyTable {
static async get(target) {
const record = await super.get(target);
return { ...record, computedField: 'value' };
}
}
Wrapping an external source
export class MyExternalData extends Resource {
static async get(target) {
const response = await fetch(`https://api.example.com/${target.id}`);
return response.json();
}
}
Making a resource an endpoint
A resource becomes an endpoint when it is exported and rest: true (and/or
graphqlSchema) is enabled in config.yaml:
rest: true
graphqlSchema:
files: schema.graphql
jsResource:
files: resources.js
Resources can also be registered programmatically with server.resources.set().
See [[harper-config-yaml]] for the extension wiring, [[harper-schema-graphql]] for
how the schema defines the tables resources extend, and [[harper-realtime]] when
subscribe, publish, or WebSocket behavior is part of the feature.
Project conventions (TS is source)
- Write resources in TypeScript under
src/.harper-app/resources.jsis a generated artifact produced bybun run build. Never editresources.jsby hand — change the TypeScript and rebuild. See [[harper-build-and-deploy]]. - Operational scripts that touch resources (seed, smoke, verify, ingest, crawl, extraction) must run from compiled JavaScript or generated Harper assets, not stale checked-in JS.
- Prefer immutable data flow:
readonlytypes, pure transformations, copies, and explicit returns. Do not mutate parameters, records, arrays, or config objects unless an API forces it, and document the exception locally. - Avoid
any, broad casts, andts-ignore. If an external API forces an escape hatch, isolate it behind a typed adapter.
Build the real thing
If an endpoint needs a schema change, a seed path, or a deploy script change, make that change — do not ship a client-side workaround or silently downgrade to a stub or mock. A change is unfinished until the local build and the relevant deployed or smoke path agree.
Verification
Run bun run build, bun run typecheck, and the smallest relevant test. For an
endpoint change, also hit the actual REST/GraphQL route against a local or deployed
Harper instance (the project smoke command) and confirm the response shape.