Skip to content

Not using Effect?

Getting Started covers the same steps with plain await and for await. You don't need Effect to use Contentia.

Installation ​

bash
pnpm add contentia effect

Contentia is built on Effect 4 and depends on effect with a caret range (pnpm view contentia dependencies.effect prints it). Any effect in that range resolves to one copy shared by your code and Contentia. An older effect in your project gets its own copy, and TypeScript rejects programs that mix the two, so upgrade it to the range's minimum.

Create a backend ​

Contentia calls a backend a repository. A repository needs three things: where the content lives, the serializers it may read and write, and the file extension new objects get.

typescript
import { jsonSerializer } from 'contentia/serializers/json';
import { FileSystemStorageRepository } from 'contentia/storage/fs';

const repo = new FileSystemStorageRepository('./content', { json: jsonSerializer }, 'json');

Keys never include the extension: the object posts/hello is stored as ./content/posts/hello.json. Getting Started explains why, and lists the other serializers.

Write and read objects ​

Repository methods return a ContentiaTask: an Effect Channel that can emit progress events and recoverable warnings, then ends with one value. ContentiaTask.runValue turns a task into an Effect<A, ContentiaError> you can yield*:

typescript
import { ContentiaTask } from 'contentia/core';
import { Effect } from 'effect';

const program = Effect.gen(function*() {
  yield* ContentiaTask.runValue(repo.createObject({
    key: 'posts/hello',
    content: { title: 'Hello, Contentia' },
  }));

  const post = yield* ContentiaTask.runValue(repo.getObject('posts/hello'));
  console.log(post.content.title); // "Hello, Contentia"

  yield* ContentiaTask.runValue(repo.updateObject({
    key: 'posts/hello',
    content: { title: 'Hello again' },
  }));
});

await Effect.runPromise(program);

Like any Effect, nothing touches storage until the program runs, and every run runs the tasks again.

Handle errors ​

A failed task fails the Effect with a typed ContentiaError. It is a class with a code, not a tagged error, so Effect.catchTag doesn't apply. Match on the code (for example not_found) with Effect.catchIf:

typescript
const title = ContentiaTask.runValue(repo.getObject('posts/missing')).pipe(
  Effect.map(post => post.content.title),
  Effect.catchIf(error => error.code === 'not_found', () => Effect.succeed('Untitled')),
);

List a folder ​

Listings return a ContentiaStream. ContentiaStream.runCollect runs one to the end and returns its items as data, together with any warnings and the closing done value:

typescript
import { ContentiaStream } from 'contentia/core';

const program = Effect.gen(function*() {
  const { data } = yield* ContentiaStream.runCollect(
    repo.listAtoms('posts', { depth: 1, pagination: {} }),
  );
  for (const atom of data) console.log(atom.key, atom.type); // "posts/hello object"
});

runCollect holds the whole listing in memory. For a large folder, turn the listing into an Effect Stream and process it item by item. A listing also carries warnings and progress events, so keep only the data elements:

typescript
import { ContentiaElement } from 'contentia/core';
import { Channel, Stream } from 'effect';

const atoms = Stream.fromChannel(
  Channel.mapDone(repo.listAtoms('posts', { depth: 1, pagination: {} }), () => undefined),
).pipe(
  Stream.filter(ContentiaElement.isData),
  Stream.map(element => element.value),
);

const program = atoms.pipe(Stream.runForEach(atom => Effect.log(atom.key)));

Stream.fromChannel expects a channel that ends without a value, so Channel.mapDone drops the listing's done value. That value describes the next page; use runCollect when you need it.

An atom is anything in the tree: an object or a folder. depth controls how far the listing recurses, and pagination accepts offset, page, or cursor (before / after) styles, depending on what the backend supports. See Content Model for the full shape.

Recoverable warnings ​

Some operations partly fail but still produce a usable result, for example a listing that skipped one corrupt file. Those come back as warnings next to the result instead of failing the Effect. runValue and the Stream above drop them. To see them, tap the task with ContentiaTask.tapRecoverableErrors, or read recoverableErrors from runCollect:

typescript
import type { ContentiaError } from 'contentia/core';

const logWarning = (error: ContentiaError) => Effect.logWarning(error.code, error.message);

const program = Effect.gen(function*() {
  const post = yield* ContentiaTask.runValue(
    ContentiaTask.tapRecoverableErrors(repo.getObject('posts/hello'), logWarning),
  );

  const { data, recoverableErrors } = yield* ContentiaStream.runCollect(
    repo.listAtoms('posts', { depth: 1, pagination: {} }),
  );
  for (const error of recoverableErrors) yield* logWarning(error);
});

Writing a repository that wraps another one? Inside your ContentiaTask.make body, drain the inner task with ContentiaTask.runValueForwarding or the inner stream with ContentiaStream.runCollectForwarding, and pass them your emit, so the inner warnings reach your caller.

Swap the backend ​

Every backend implements the same StorageRepository interface. Put the repository behind a service, and switching backends means providing a different Layer. The program that reads and writes content stays the same:

typescript
import type { StorageRepository } from 'contentia/storage';
import { Context, Effect, Layer } from 'effect';

class Content extends Context.Service<Content, StorageRepository>()('app/Content') {}

const readTitle = Effect.gen(function*() {
  const repo = yield* Content;
  const post = yield* ContentiaTask.runValue(repo.getObject('posts/hello'));
  return post.content.title;
});
ts
import { jsonSerializer } from 'contentia/serializers/json';
import { FileSystemStorageRepository } from 'contentia/storage/fs';

const ContentLive = Layer.succeed(
  Content,
  new FileSystemStorageRepository('./content', { json: jsonSerializer }, 'json'),
);

await Effect.runPromise(readTitle.pipe(Effect.provide(ContentLive)));
ts
import { jsonSerializer } from 'contentia/serializers/json';
import { R2StorageRepository } from 'contentia/storage/r2';

// inside a Worker's fetch handler, where `env` holds the bucket binding
const ContentLive = Layer.succeed(
  Content,
  new R2StorageRepository(env.CONTENT_BUCKET, { json: jsonSerializer }, 'json'),
);

await Effect.runPromise(readTitle.pipe(Effect.provide(ContentLive)));

Adapters lists every backend: git hosts, object storage, SQL databases, the filesystem, and the browser.

GitHubGitHub GitLabGitLab BitbucketBitbucket GitHub CDNGitHub CDN Cloudflare R2Cloudflare R2 S3-compatibleS3-compatible Drizzle ORMDrizzle ORM FilesystemFilesystem Browser File SystemBrowser File System Web StorageWeb Storage WebDAVWebDAV ObsidianObsidian JSON:API proxyJSON:API proxy

Serve it over HTTP ​

buildJsonApi turns any storage repository into a JSON:API handler. It returns a plain fetch(request): Promise<Response> function, not an Effect, so you serve it the same way with or without Effect:

typescript
import { serve } from '@hono/node-server';
import { allowAll } from 'contentia/json-api';
import { buildJsonApi } from 'contentia/storage/api';

const api = buildJsonApi({ repo, authorize: allowAll });
serve({ fetch: api.fetch, port: 3000 });

allowAll leaves the API open, which is only safe on a local dev server. Serve it over HTTP covers authorize, and Mount the API covers the other runtimes and mounting the API in a framework.

Next steps ​

  • Repositories: the repository pattern, and how to write your own
  • Content Model: atoms, folders, the body convention, change tracking
  • Architecture: how the storage, documents, and API layers fit together
  • Adapters: every supported backend
  • HTTP API: every route and schema, plus conventions, pagination, and errors
  • Imports: every import path and its install command