Page MenuHomeSealhub
Files F9582847

README.md
No OneTemporary
Actions

README.md
View Options

# Sealious
Sealious is a declarative node.js framework. It creates a full-featured REST-ful
API (with user and session management) based on a declarative description of the
database schema and policies.
All development is handled on [Sealcode's Phabricator](https://hub.sealcode.org/source/sealious/). A [read-only mirror is stored on Github](https://github.com/sealcode/sealious).
## Quick links
### Examples
It's best to learn by example. Here are some applications written with the
current version of Sealious:
- [Sealious Playground](https://hub.sealcode.org/diffusion/PLAY/) - simple
TODO app written in Sealious and Hotwire. Contains docker setup for mongo,
linting, typescript etc. Good starting point for a new app.
### References
- [Creating collections](https://hub.sealcode.org/source/sealious/browse/dev/src/chip-types/creating-collections.remarkup)
- [List of all endpoints automatically created by
Sealious](https://hub.sealcode.org/source/sealious/browse/dev/endpoints.remarkup)
- [List of Built-in field
types](https://hub.sealcode.org/source/sealious/browse/dev/src/app/base-chips/field-types/field-types.remarkup)
- [List of build-in Policies](https://hub.sealcode.org/source/sealious/browse/dev/src/app/policy-types/policy-types.remarkup)
- [ORM style accessors to database](https://hub.sealcode.org/source/sealious/browse/dev/orm.remarkup)
- [Theory and practice behind Context](https://hub.sealcode.org/source/sealious/browse/dev/context.remarkup)
- [Creating custom
field-types](https://hub.sealcode.org/source/sealious/browse/dev/src/app/base-chips/field-types/creating-field-types.remarkup)
- [Creating custom Policy
types](https://hub.sealcode.org/source/sealious/browse/dev/src/app/policy-types/creating-policy-types.remarkup)
- [How User Roles work in Sealious](https://hub.sealcode.org/source/sealious/browse/dev/roles.remarkup)
- [Handling long-running processes](https://hub.sealcode.org/source/sealious/browse/dev/src/data-structures/long-running-process.remarkup)
## Example app
Install sealious with `npm install --save sealious`. Then, in your index.ts:
```
lang=typescript
import { resolve } from "path";
import Sealious, { App, Collection, FieldTypes, Policies } from "sealious";
const locreq = _locreq(__dirname);
const app = new (class extends App {
config = {
datastore_mongo: {
host: "localhost",
port: 20723,
db_name: "sealious-playground",
},
email: {
from_address: "sealious-playground@example.com",
from_name: "Sealious playground app",
},
"www-server": {
port: 8080, //listen on this port
},
};
manifest = {
name: "My ToDo list",
logo: resolve(__dirname, "../assets/logo.png"),
version: "0.0.1",
default_language: "en",
base_url: "localhost:8080",
admin_email: "admin@example.com",
colors: {
primary: "#5294a1",
},
};
collections = {
...App.BaseCollections,
tasks: new (class extends Collection {
fields = {
title: new FieldTypes.Text(),
done: new FieldTypes.Boolean(),
};
defaultPolicy = new Policies.Public();
})(),
};
})();
app.start();
```
Assuming you have the mongo database running, that's it! The above script
creates a fully functional REST API with field validation, error messages, etc.
Try sending as POST message to `http://localhost:8080/api/v1/collections/tasks`
to see the API in action. You can learn more about the endpoints created by
Sealious for each collection [in ./endpoints.remarkup doc
file](https://hub.sealcode.org/source/sealious/browse/dev/endpoints.remarkup).
The app created by the above code also has some handy ORM-style methods to access and modify items within the collection:
```
lang=typescript
import {Context} from "sealious";
const tasks = app.collections.tasks.list(new Context(app)).fetch()
```
To learn more about the ORM methods, see [./orm.remarkup doc file](https://hub.sealcode.org/source/sealious/browse/dev/orm.remarkup).
## Learning Resources
### FAQ
#### How do I add a custom route?
Sealious uses `koa` and [@koa/router](https://github.com/koajs/router) to handle HTTP. To add a simple static route:
```
lang=typescript
app.HTTPServer.router.get("/", async (ctx) => {
ctx.body = html(/* HTML */ `
<body>
<h1>Hello, world!</h1>
</body>
`);
});
```
If you need to perform some user-specific tasks, or need to extract the context in order to call the database, use the `extractContext` Middleware:
```
lang=typescript
import {Middlewares} from "sealious";
app.HTTPServer.router.get("/", Middlewares.extractContext(), async (ctx) => {
const {items: tasks} = await app.collections.tasks.list(ctx.$context).fetch();
ctx.body = html(/* HTML */ `
<body>
<h1>My To do list</h1>
{tasks.map(task=>task.get("title")).join("")}
</body>
`);
});
```
#### How do I serve static files?
```
lang=typescript
app.HTTPServer.addStaticRoute("/", locreq.resolve("public"));
```
#### How do I set up SMTP?
When mailer isn't specified, Sealious log messages to `stdout` instead of
sending them via email. To make it use an SMTP connection, add the following to
the app definition:
```
lang=typescript
import { SMTPMailer } from "sealious";
// in app definition:
const app = new (class extends App {
config = {
/* ... */
};
mailer = new SMTPMailer({
host: "localhost",
port: 1025,
user: "any",
password: "any",
});
})();
```
#### How do I change a policy for a built-in collection?
```
lang=typescript
const app = new (class extends App {
config = {
/* ... */
};
manifest = {
/* ... */
};
collections = {
...App.BaseCollections,
users: App.BaseCollections.users.setPolicy(
"create",
new Policies.Public()
),
};
})();
```
#### How do I add a field to a built-in collection?
```
lang=typescript
import {Collections} from "sealious";
const app = new (class extends App {
config = {
/* ... */
};
manifest = {
/* ... */
};
collections = {
...App.BaseCollections,
users: new (class users extends Collections.users {
fields = {
...App.BaseCollections.users.fields,
description: new FieldTypes.Text(),
};
})(),
};
})();
```
#### How to create a custom login endpoint?
```
lang=typescript
function LoginForm(username: string = "", error_message?: string) {
return /* HTML */ `
<form method="POST" action="/login">
${error_message ? `<div>${error_message}</div>` : ""}
<label for="username">
Username:
<input
id="username"
name="username"
type="text"
value="${username}"
required
/>
</label>
<label for="password"
>Password:
<input
id="password"
name="password"
type="password"
value="${username}"
required
/></label>
<input type="submit" value="log in" />
</form>
`;
}
const router = app.HTTPServer.router;
router.get("/login", async (ctx) => {
ctx.body = LoginForm();
});
router.post("/login", Middlewares.parseBody(), async (ctx) => {
try {
const session_id = await ctx.$app.collections.sessions.login(
ctx.$body.username as string,
ctx.$body.password as string
);
ctx.cookies.set("sealious-session", session_id, {
maxAge: 1000 * 60 * 60 * 24 * 7,
secure: ctx.request.protocol === "https",
overwrite: true,
});
ctx.redirect("/user");
ctx.status = 303; // more standards- and hotwire-friendly
} catch (e) {
ctx.body = LoginForm(ctx.$body.username as string, e.message);
}
});
```
#### How to log out a user?
Create an endpoint where you call the `sessions.logout` function:
```
lang=ts
router.get("/logout", async (ctx) => {
const session_id = ctx.cookies.get("sealious-session");
ctx.$app.collections.sessions.logout(ctx.$context, session_id);
ctx.status = 303; // more standards- and hotwire-friendly
});
```
#### How to set up a default value to a field?
It's possible, but currently not pretty. This will be fixed in the future.
```
lang=typescript
const tasks = new (class extends Collection {
fields = {
title: new FieldTypes.Text(),
done: new (class extends FieldTypes.Boolean {
hasDefaultValue = () => true;
async getDefaultValue() {
return false;
}
})(),
};
defaultPolicy = new Policies.Public();
})();
```
#### How to sort by modification/creation time?
```
lang=typescript
app.collections.entries
.suList()
.sort({ "_metadata.modified_at": "desc" }) // or: _metadata.created_at
.fetch();
```
### How to add custom validation to a collection?
```
lang=typescript
export class CollectionWithComplexValidation extends Collection {
fields = {
color: new FieldTypes.Color(),
};
async validate(_: Context, body: CollectionItemBody) {
if ((body.getInput("color") as string).includes("green")) {
return [{
error: "Green is not a creative color",
fields: ["color"],
}];
}
return [];
}
defaultPolicy = new Policies.Public();
}
```
### How to do one-time collection populate?
```
lang=typescript, name=collection.ts
const my_collection = new (class extends Collection {
// ...
async populate(): Promise<void> {
if (await this.app.Metadata.get("my_collection_populated")) {
return;
}
const app = this.app as TheApp;
// create the resources here using the regular CRUD functions
await this.app.Metadata.set("my_collection_populated", "true");
}
})();
```
```
lang=typescript, name=index.ts
void app.start().then(async () => {
await app.collections.my_collection.populate();
});
```
### How to send an email?
```
lang=typescript
import { EmailTemplates } from "sealious";
const message = await EmailTemplates.Simple(ctx.$app, {
text: "Click this link to finish registration:",
subject: "Rejestracja w zmagazynu.pl",
to: ctx.$body.email as string,
buttons: [
{
text: "Finish registration",
href: `${ctx.$app.manifest.base_url}/finish-registration?token=${some_token}`,
},
],
});
message.send(ctx.$app);
```
### How to translate strings returned by the app?
You can add custom translations to the `app.strings` object.
```
lang=typescript
const app = new (class extends App {
// ...
strings = {
Welcome: "Witamy",
you_have_n_points: (n: number) => `Masz ${n} punktów.`,
};
})();
```
You can then use the translation anywhere in your app like so:
```
lang=typescript
app.getString("Welcome", [], "Welcome!");
```
Note: not all strings generated by Sealious are translatable yet.
### How to run custom code when an item is created/edited?
When `DerivedValue` / `CachedValue` / `ReverseSingleReference` aren't enough for
the logic of the application, you can use custom logic based on events.
```
lang=typescript
export default class Patrons extends Collection {
fields = {
fullname: new FieldTypes.Text(),
amount_monthly: new FieldTypes.Float(),
platform: new FieldTypes.Enum(["patronite", "liberapay", "manual"]),
};
defaultPolicy = new Policies.Public();
async init(app: TheApp, collection_name: string) {
await super.init(app, collection_name);
this.on("after:create", async ([context, item, event]) => {
await app.collections["patron-events"].create(context, {
message: `Added a new patron from ${item.get(
"platform"
)} for the amount: ${item.get("amount_monthly")}`,
timestamp: Date.now(),
patron: item.id,
});
});
}
}
```
### How to detect changes in particular fields?
When `DerivedValue` / `CachedValue` / `ReverseSingleReference` aren't enough for
the logic of the application, you can use custom logic based on events.
```
lang=ts
export default class Patrons extends Collection {
fields = {
fullname: new FieldTypes.Text(),
email: new FieldTypes.Email(),
amount_monthly: new FieldTypes.Float(),
};
defaultPolicy = new Policies.Public();
async init(app: TheApp, collection_name: string) {
await super.init(app, collection_name);
this.on("after:edit", async ([context, item]) => {
const changes = await item.summarizeChanges(context);
// when `amount_monthly` changes from 10 to 12, this will be `{amount_monthly: {was: 10, is: 12}}`
});
}
}
```
### How to hide from public unpublished items?
```lang=ts
export default class Articles extends Collection {
fields = {
published: new FieldTypes.Boolean()
}
named_filters = {
published: new SpecialFilters.Matches("articles", { published: true }),
};
policies = {
show: new Policies.If(
"articles",
"published",
new Policies.Public(),
new Roles(["admin"])
),
};
}
```
### How to configure Atom (RSS) feeds for a collection
Sealious will generate an Atom feed automatically for each collection
that has a `title` field. If you want to enable an atom feed for a
collection that does not have a `title` field, add this to the
collection declaration:
```
lang=ts
hasFeed(){return true}
```
To change what fields and in what way are used for generating the Atom
feed, you can customize the `mapFieldsToFeed` method of the collection:
```
lang=ts
class Posts extends Collection {
readonly fields = {
title: new FieldTypes.Text(),
feedTitle: new FieldTypes.Text(),
content: new FieldTypes.Text(),
} as const;
mapFieldsToFeed(): FieldEntryMapping<this> {
return {
...super.mapFieldsToFeed(),
title: async (_ctx, item) =>
item.get("feedTitle") || item.get("title") || "Untitled",
};
}
}
```
In order for the Atom feeds to be automatically discoverable, make
sure to add the output of
```
lang=ts
app.getFeedHTMLMetatags()
```
to the content of the `<head>` tag of your HTML page.
### How to validate field value transition
You can use .setTransitionChecker method on each field to add custom
logic that will be decide every time this field changes value, whether
or not this change is allowed:
```
lang=ts
new (class extends Collection {
fields = {
timestamp: new FieldTypes.Int().setTransitionChecker(
(_, old_value, new_value) => {
return old_value == undefined || parseInt(String(new_value)) > old_value
? { valid: true }
: {
valid: false,
reason: "timestamps cannot go back in time",
};
},
),
};
})();
```
## Development
To run test outside of docker, run:
```
docker-compose up -d
npm run test
```
If you want to debug the tests, run:
```
npm run test -- --debug
```

File Metadata

Mime Type
text/x-java
Expires
Sat, Oct 11, 07:58 (1 d, 7 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
983495
Default Alt Text
README.md (14 KB)

Event Timeline