Encore.ts

https://encore.dev/docs/ts
Admin
Encore.ts is a high-performance API framework for building robust, type-safe backend applications...
Tokens:171,850
Snippets:1,551
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Better Auth and pg

Source: https://encore.dev/docs/ts/develop/integrations/better-auth

Install the Better Auth library and the PostgreSQL client.

```bash
$ npm install better-auth pg
```

--------------------------------

### Create static files example

Source: https://encore.dev/docs/ts/frontend/hosting

Command to create a static files example that serves HTML files from a directory.

```bash
$ encore app create --example=ts/static-files
```

--------------------------------

### Install Encore and create app

Source: https://encore.dev/docs/ts

Run these commands in your terminal to install Encore and create a new application. The commands are executed sequentially: first the installation script is run, then the app creation command is invoked.

```powershell
iwr https://encore.dev/install.ps1 | iex &&
encore app create
```

--------------------------------

### Example migration command

Source: https://encore.dev/docs/ts/develop/orms/prisma

Example of generating a migration named 'add-user-role'.

```bash
npx prisma migrate dev --name add-user-role
```

--------------------------------

### Create a new app from the example

Source: https://encore.dev/docs/ts/develop/integrations/polar

Use this command to quickly create a new Encore app with the Polar example.

```bash
$ encore app create --example=ts/polar

```

--------------------------------

### Install Resend SDK

Source: https://encore.dev/docs/ts/develop/integrations/resend

Installs the Resend SDK for sending emails.

```bash
$ npm install resend

```

--------------------------------

### Create Encore app from Resend example

Source: https://encore.dev/docs/ts/develop/integrations/resend

Creates a new Encore app from the Resend example template.

```bash
$ encore app create --example=ts/resend

```

--------------------------------

### Create GraphQL example app

Source: https://encore.dev/docs/ts/frontend/request-client

Use this command to create an example Encore.ts GraphQL backend with a basic book CRUD service.

```bash
$ encore app create --example=ts/graphql
```

--------------------------------

### Install the Polar SDK

Source: https://encore.dev/docs/ts/develop/integrations/polar

Install the @polar-sh/sdk package.

```bash
$ npm install @polar-sh/sdk

```

--------------------------------

### Create a new app from the Better Auth example

Source: https://encore.dev/docs/ts/develop/integrations/better-auth

Use the Encore CLI to create a new app from the Better Auth example template.

```bash
$ encore app create --example=ts/betterauth
```

--------------------------------

### Install Prisma and dependencies

Source: https://encore.dev/docs/ts/develop/orms/prisma

Install Prisma CLI as a dev dependency and the Prisma client, PostgreSQL adapter, and dotenv as runtime dependencies.

```bash
npm install prisma --save-dev
npm install @prisma/client @prisma/adapter-pg dotenv --save
```

--------------------------------

### StringListKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores ordered lists of string values. Shows pushing items, getting a range, and popping an item.

```typescript
import { StringListKeyspace } from "encore.dev/storage/cache";

const recentItems = new StringListKeyspace<{ userId: string }>(cluster, {
  keyPattern: "recent/:userId",
});

// Push items to the list
await recentItems.pushRight({ userId: "user123" }, "item1", "item2");

// Get items from the list
const items = await recentItems.getRange({ userId: "user123" }, 0, -1); // Get all

// Pop an item (returns undefined if empty)
const lastItem = await recentItems.popRight({ userId: "user123" });
```

--------------------------------

### Query Parameter Example

Source: https://encore.dev/docs/ts/primitives/defining-apis

Shows how to define query parameters using the Query type and default behavior for GET, HEAD, DELETE requests.

```APIDOC
## Query Parameter Example

### Description
Demonstrates using the Query type to specify fields parsed from the query string.

### Parameters
#### Query Parameters
- **limit** (number) - Required - Always parsed from the query string.
- **author** (string) - Optional - Parsed from query string for GET, HEAD, DELETE; otherwise from body.

### Request Example
GET /posts?limit=10&author=John
```

--------------------------------

### StaticOptions headers example

Source: https://encore.dev/docs/ts/runtime/api

Example of setting custom HTTP headers for static files, including Cache-Control and X-Content-Type-Options.

```typescript
headers: {
  "Cache-Control": "public, max-age=3600",
  "X-Content-Type-Options": "nosniff",
}
```

--------------------------------

### Install Resend and React Email components

Source: https://encore.dev/docs/ts/develop/integrations/resend

Installs Resend and React Email components for building email templates.

```bash
$ npm install resend @react-email/components

```

--------------------------------

### Create streaming-chat example app

Source: https://encore.dev/docs/ts/primitives/streaming-apis

Creates a new Encore application from the streaming-chat example template, which demonstrates a WebSocket stream from a web frontend.

```bash
$ encore app create --example=ts/streaming-chat
```

--------------------------------

### StringSetKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores unordered sets of unique string values. Shows adding members, checking membership, getting all members, and removing members.

```typescript
import { StringSetKeyspace } from "encore.dev/storage/cache";

const tags = new StringSetKeyspace<{ articleId: string }>(cluster, {
  keyPattern: "tags/:articleId",
});

// Add members to the set
await tags.add({ articleId: "post1" }, "typescript", "encore", "backend");

// Check membership
const hasTag = await tags.contains({ articleId: "post1" }, "typescript");

// Get all members
const allTags = await tags.items({ articleId: "post1" });

// Remove members
await tags.remove({ articleId: "post1" }, "backend");
```

--------------------------------

### Install dependencies from monorepo root

Source: https://encore.dev/docs/ts/develop/monorepo/turborepo

Run `npm install` at the monorepo root to install dependencies for all workspaces, including Turborepo.

```bash
$ npm install
```

--------------------------------

### Generate and apply initial migration

Source: https://encore.dev/docs/ts/develop/orms/prisma

Runs Prisma migrate to create and apply the initial migration, then starts the Encore development server.

```bash
npx prisma migrate dev --name init
encore run
```

--------------------------------

### Install Vitest with npm

Source: https://encore.dev/docs/ts/tutorials/rest-api

Run this command to install the Vitest testing framework as a dev dependency. Vitest works well with Encore, but other TypeScript testing frameworks can be used.

```bash
$ npm i --save-dev vitest
```

--------------------------------

### db.begin

Source: https://encore.dev/docs/ts/primitives/databases

Starts a new transaction, returning a transaction object that can be committed or rolled back.

```APIDOC
## db.begin

### Description
Starts a new transaction. The transaction type implements `AsyncDisposable`, which automatically rolls back the transaction if it is not explicitly committed or rolled back.

### Method
begin

### Parameters
None.

### Request Example
```
await using tx = await db.begin();

await db.exec`
  INSERT INTO todo_item (title, done)
  VALUES (${title1}, false)
`;

await db.exec`
  INSERT INTO todo_item (title, done)
  VALUES (${title2}, false)
`;

await tx.commit();
```

### Response
#### Success Response
- **tx** (Transaction) - A transaction object with a `commit` method.

```

--------------------------------

### Example HTTP request to echo endpoint

Source: https://encore.dev/docs/ts/primitives/validation

Shows an example HTTP request to the echo endpoint, including a query parameter, a custom header, and a JSON body.

```http
POST /echo?query=hello HTTP/1.1
Content-Type: application/json
X-Header: this is a header
{
   "body": "a body",
}
```

--------------------------------

### FloatKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores 64-bit floating-point values. Shows setting a value and incrementing by a float amount.

```typescript
import { FloatKeyspace } from "encore.dev/storage/cache";

const scores = new FloatKeyspace<{ oddsId: string }>(cluster, {
  keyPattern: "odds/:oddsId",
});

// Set a value
await scores.set({ oddsId: "game1" }, 1.5);

// Increment by a float amount
const newOdds = await scores.increment({ oddsId: "game1" }, 0.1);
```

--------------------------------

### Get public URL of an object

Source: https://encore.dev/docs/ts/primitives/object-storage

Use the `publicUrl` method on a public bucket to get the public URL for a specified object. This example logs the URL for 'my-image.jpeg'.

```typescript
const url = publicProfilePictures.publicUrl("my-image.jpeg");
console.log(`Public URL: ${url}`);
```

--------------------------------

### NumberListKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores ordered lists of numeric values. Shows pushing scores and getting all items.

```typescript
import { NumberListKeyspace } from "encore.dev/storage/cache";

const scoreHistory = new NumberListKeyspace<{ playerId: string }>(cluster, {
  keyPattern: "scores/:playerId",
});

// Push scores
await scoreHistory.pushRight({ playerId: "player1" }, 100, 200, 150);

// Get all scores
const scores = await scoreHistory.items({ playerId: "player1" });
```

--------------------------------

### StructKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores structured data (objects) serialized as JSON. Shows setting and getting a structured value with a custom interface.

```typescript
import { StructKeyspace } from "encore.dev/storage/cache";

interface UserProfile {
  name: string;
  email: string;
  preferences: {
    theme: "light" | "dark";
    notifications: boolean;
  };
}

const profiles = new StructKeyspace<{ userId: string }, UserProfile>(cluster, {
  keyPattern: "profile/:userId",
  defaultExpiry: expireIn(3600 * 1000),
});

// Set a structured value
await profiles.set(
  { userId: "user123" },
  {
    name: "Alice",
    email: "alice@example.com",
    preferences: { theme: "dark", notifications: true },
  }
);

// Get the value
const profile = await profiles.get({ userId: "user123" });
```

--------------------------------

### Create Next.js starter app

Source: https://encore.dev/docs/ts/frontend/hosting

Command to create a Next.js + Encore TS Web App Starter example, with frontend hosted on Vercel and backend on Encore.

```bash
$ encore app create --example=ts/nextjs-starter
```

--------------------------------

### Default query string parsing for GET, HEAD, DELETE

Source: https://encore.dev/docs/ts/primitives/validation

For GET, HEAD, and DELETE requests, parameters are read from the query string by default, so the Query type is not necessary. The example shows a field that is always a query parameter and one that is query only for those methods.

```typescript
import { Query } from "encore.dev/api";

interface Schema {
  limit: Query<number>; // always a query parameter
  author: string; // query if GET, HEAD or DELETE, otherwise body parameter
}
```

--------------------------------

### StringKeyspace example

Source: https://encore.dev/docs/ts/primitives/caching

Stores string values. Shows setting, getting, and deleting a value. Additional operations: append, getRange, setRange, len.

```typescript
import { StringKeyspace } from "encore.dev/storage/cache";

const tokens = new StringKeyspace<{ tokenId: string }>(cluster, {
  keyPattern: "token/:tokenId",
  defaultExpiry: expireIn(3600 * 1000), // 1 hour
});

// Set a value
await tokens.set({ tokenId: "abc123" }, "user-token-value");

// Get a value (returns undefined on cache miss)
const token = await tokens.get({ tokenId: "abc123" });

// Delete a value
await tokens.delete({ tokenId: "abc123" });
```

--------------------------------

### Nest controller example for cats

Source: https://encore.dev/docs/ts/how-to/nestjs

A typical Nest controller with @Controller('cats') that defines create, findAll, and findOne endpoints. It uses @Post, @Get, @Roles, @Body, @Param, and ParseIntPipe.

```typescript
@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {
  }

  @Post()
  @Roles(['admin'])
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }

  @Get()
  async findAll(): Promise<Cat[]> {
    return this.catsService.findAll();
  }

  @Get(':id')
  findOne(
    @Param('id', new ParseIntPipe())
      id: number,
  ) {
    return this.catsService.get(id);
  }
}
```

--------------------------------

### Mocking GET and POST request client methods in tests

Source: https://encore.dev/docs/ts/frontend/request-client

Example test suite that mocks the List (GET) method and spies on the Add (POST) method of the site.ServiceClient. It verifies the List method is called once and the Add method is called with the correct parameters. Note that the List method must be mocked on the prototype because the request client is not yet initialized when creating the mock.

```typescript
import { render, waitForElementToBeRemoved } from "@testing-library/react";
import App from "./App";
import { site } from "./client";
import { userEvent } from "@testing-library/user-event";

describe("App", () => {
  beforeEach(() => {
    // Return mocked data from the List (GET) endpoint
    jest
      .spyOn(site.ServiceClient.prototype, "List")
      .mockReturnValue(Promise.resolve({
        sites: [{
          id: 1,
          url: "test.dev"
        }]
      }));

    // Spy on the Add (POST) endpoint
    jest.spyOn(site.ServiceClient.prototype, "Add");
  });

  it("render sites", async () => {
    render(<App />);
    await waitForElementToBeRemoved(() => screen.queryByText("Loading..."));

    // Verify that the List endpoint has been called
    expect(site.ServiceClient.prototype.List).toBeCalledTimes(1);

    // Verify that the sites are rendered with our mocked data
    screen.getAllByText("test.dev");
  });

  it("add site", async () => {
    render(<App />);
    await waitForElementToBeRemoved(() => screen.queryByText("Loading..."));

    // Interact with the page and add 'another.com'
    await userEvent.click(screen.getByText("Add website"));
    await userEvent.type(
      screen.getByPlaceholderText("google.com"),
      "another.com",
    );
    await userEvent.click(screen.getByText("Save"));

    // Verify that the Add endpoint has been called with the correct parameters
    expect(site.ServiceClient.prototype.Add).toHaveBeenCalledWith({
      url: "another.com",
    });
  });
})

```

--------------------------------

### Launch Prisma Studio

Source: https://encore.dev/docs/ts/develop/orms/prisma

Run this command to open Prisma Studio, a GUI for your database, at http://localhost:5555.

```bash
npx prisma studio
```

--------------------------------

### begin()

Source: https://encore.dev/docs/ts/runtime/storage-sqldb

Begins a database transaction. Prefer the `await using` pattern to automatically roll back if neither commit nor rollback is called.

```APIDOC
## Method: begin()

### Description
Begins a database transaction. Prefer the `await using` pattern, which automatically rolls back the transaction if neither `commit` nor `rollback` is called before the variable goes out of scope.

### Returns
- **Promise<Transaction>** - A transaction object that implements `AsyncDisposable`.
```

--------------------------------

### Error handling for cache operations

Source: https://encore.dev/docs/ts/primitives/caching

Shows how to import and use cache error types. get() returns undefined on cache miss, while replace() throws CacheMiss if the key doesn't exist. The example catches CacheMiss and rethrows other errors.

```typescript
import { CacheError, CacheMiss, CacheKeyExists } from "encore.dev/storage/cache";

// get returns undefined on cache miss
const value = await keyspace.get(key);
if (value === undefined) {
  // Key doesn't exist in cache
}

// replace throws CacheMiss if the key doesn't exist
try {
  await keyspace.replace(key, newValue);
} catch (err) {
  if (err instanceof CacheMiss) {
    console.log("Key doesn't exist, can't replace");
  }
  throw err;
}
```

--------------------------------

### Create book service directory and file

Source: https://encore.dev/docs/ts/tutorials/graphql

Creates the `book` directory and an empty `encore.service.ts` file in the application root, which will hold the Book service implementation.

```bash
$ mkdir book
$ touch book/encore.service.ts

```

--------------------------------

### Create .env file with connection strings

Source: https://encore.dev/docs/ts/develop/orms/prisma

Defines environment variables for the main and shadow database connection strings used in local development.

```bash
# Connection strings for local development
DB_URL=<main-database-connection-string>
SHADOW_DB_URL=<shadow-database-connection-string>
```

--------------------------------

### get()

Source: https://encore.dev/docs/ts/runtime/storage-cache

Gets the value stored at key. If the key does not exist, it returns `undefined`.

```APIDOC
## get(key)

### Description
Gets the value stored at key. If the key does not exist, it returns `undefined`.

### Method
`get(key): Promise<V | undefined>`

### Parameters
- **key** (`K`) - Required - The key to get.

### Returns
`Promise<V | undefined>` - The value, or `undefined` if the key does not exist.

### See
https://redis.io/commands/get/

### Inherited from
`BasicKeyspace.get`
```

--------------------------------

### get()

Source: https://encore.dev/docs/ts/runtime/storage-cache

Gets the value stored at key. If the key does not exist, it returns `undefined`.

```APIDOC
## get(key)

### Description
Gets the value stored at key. If the key does not exist, it returns `undefined`.

### Method
`get`

### Parameters
- **key** (`K`) - Required - The key to get.

### Returns
`Promise<number | undefined>` - The value, or `undefined` if the key does not exist.

### See
https://redis.io/commands/get/
```

--------------------------------

### Create migrations folder and initial migration file

Source: https://encore.dev/docs/ts/tutorials/rest-api

Commands to create the migrations directory and an initial migration file named 001_create_tables.up.sql. The file name format is important: it must start with 001_ and end with .up.sql.

```bash
$ mkdir url/migrations
$ touch url/migrations/001_create_tables.up.sql
```

--------------------------------

### Create project directory structure

Source: https://encore.dev/docs/ts/develop/orms/prisma

Shows the required directory layout for the service, including database.ts, prisma folder, and api.ts.

```text
my-service/
├── database.ts
├── prisma/
│   ├── schema.prisma
│   ├── migrations/
│   ├── generated/     (will be created by Prisma)
│   └── client.ts
└── api.ts
```

--------------------------------

### Initialize SQLDatabase and get connection string

Source: https://encore.dev/docs/ts/develop/orms

Creates a named database 'siteDB' with a migration directory and retrieves its connection string for use with an ORM or migration framework.

```typescript
import { SQLDatabase } from "encore.dev/storage/sqldb";

// Initialize a named database with migration directory
const SiteDB = new SQLDatabase("siteDB", {
  migrations: "./migrations",
});

// Retrieve the connection string for ORM use
const connStr = SiteDB.connectionString;
```

--------------------------------

### get(key)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Gets the value stored at key. If the key does not exist, it returns undefined.

```APIDOC
## Method: get(key)

### Description
Gets the value stored at key. If the key does not exist, it returns `undefined`.

### Parameters
- **key** (`K`) - Required - The cache key.

### Returns
`Promise<string | undefined>` - The value, or `undefined` if the key does not exist.

### See
https://redis.io/commands/get/

### Inherited from
`BasicKeyspace.get`
```

--------------------------------

### trim(key, start, stop, options?): Promise<void>

Source: https://encore.dev/docs/ts/runtime/storage-cache

Trims the list stored at key to only contain the elements between the indices `start` and `stop` (inclusive). Out of range indices are valid and treated as the start or end of the list.

```APIDOC
## trim(key, start, stop, options?)

### Description
Trims the list stored at key to only contain the elements between the indices `start` and `stop` (inclusive). Both are zero-based indices. Negative indices can be used to indicate offsets from the end of the list. Out of range indices are valid and are treated as if they specify the start or end of the list, respectively. If `start` > `stop` the end result is an empty list.

### Method
trim

### Signature
`trim(key, start, stop, options?): Promise<void>`

### Parameters
- **key** (`K`) - Required - The cache key.
- **start** (`number`) - Required - Start index (inclusive).
- **stop** (`number`) - Required - Stop index (inclusive).
- **options** (`WriteOptions`) - Optional - Write options.

### Returns
`Promise<void>`

### See
https://redis.io/commands/ltrim/

### Inherited from
`ListKeyspace.trim`
```

--------------------------------

### new SQLDatabase(name, cfg?)

Source: https://encore.dev/docs/ts/runtime/storage-sqldb

Constructs a new SQLDatabase object, provisioning a database with the given name. Use Database.Named(name) to reference an existing database.

```APIDOC
## Constructor: new SQLDatabase(name, cfg?)

### Description
Constructs a new SQLDatabase object, provisioning a database with the given name. Use Database.Named(name) to reference an existing database.

### Parameters
- **name** (string) - Required - The name of the database.
- **cfg?** (SQLDatabaseConfig) - Optional - Configuration for the database.

### Returns
- **SQLDatabase** - The new SQLDatabase instance.
```

--------------------------------

### Initial database migration file (001_create_tables.up.sql)

Source: https://encore.dev/docs/ts/tutorials/rest-api

SQL migration file that creates the url table with id and original_url columns. This is the initial schema for the database.

```sql
url/migrations/001_create_tables.up.sql
CREATE TABLE url (
	id TEXT PRIMARY KEY,
	original_url TEXT NOT NULL
);
```

--------------------------------

### Build Docker image for self-hosting

Source: https://encore.dev/docs/ts/develop/integrations/polar

Build a Docker image for self-hosting the Encore app.

```bash
$ encore build docker my-app:latest

```

--------------------------------

### database.ts: Set up Sequelize with SQLDatabase

Source: https://encore.dev/docs/ts/develop/orms/sequelize

Initializes a SQLDatabase instance and configures Sequelize with its connection string. Defines a User model and shows an example usage of counting all users. Requires the 'sequelize' and 'encore.dev/storage/sqldb' packages.

```typescript
import {
  Model,
  InferAttributes,
  InferCreationAttributes,
  CreationOptional,
  DataTypes,
  Sequelize,
} from "sequelize";
import { SQLDatabase } from "encore.dev/storage/sqldb";

// Create SQLDatabase instance with migrations configuration
const DB = new SQLDatabase("encore_sequelize_test", {
  migrations: "./migrations",
});

// Initialize Sequelize with the connection string
const sequelize = new Sequelize(DB.connectionString);

// Define the User model
class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
  declare id: CreationOptional<number>;
  declare name: string;
  declare surname: string;
}

// Example usage: Count all users
const count = await User.count();

```

--------------------------------

### Create the url service directory and file

Source: https://encore.dev/docs/ts/tutorials/rest-api

Creates the url directory and the encore.service.ts file in the application root. Run these shell commands before adding the service definition code.

```bash
$ mkdir url
$ touch url/encore.service.ts
```

--------------------------------

### trim(key, start, stop, options?)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Trims the list stored at key to only contain the elements between the indices `start` and `stop` (inclusive).

```APIDOC
## trim(key, start, stop, options?)

### Description
Trims the list stored at key to only contain the elements between the indices `start` and `stop` (inclusive). Both are zero-based indices. Negative indices can be used to indicate offsets from the end of the list. Out of range indices are valid and are treated as if they specify the start or end of the list. If `start` > `stop` the end result is an empty list.

### Method
trim

### Parameters
- **key** (`K`) - The cache key.
- **start** (`number`) - Start index (inclusive).
- **stop** (`number`) - Stop index (inclusive).
- **options?** (`WriteOptions`) - Optional write options.

### Returns
`Promise<void>`

### See
https://redis.io/commands/ltrim/
```

--------------------------------

### Create a SQL database with SQLDatabase

Source: https://encore.dev/docs/ts/primitives/databases

Imports `encore.dev/storage/sqldb` and calls `new SQLDatabase` to create a database named 'todo', specifying the `migrations` directory for schema definitions. Requires Docker to be running locally when using `encore run`.

```typescript
import { SQLDatabase } from "encore.dev/storage/sqldb";

// Create the todo database and assign it to the "db" variable
const db = new SQLDatabase("todo", {
  migrations: "./migrations",
});

// Then, query the database using db.query, db.exec, etc.
```

--------------------------------

### Using cloud-specific services with appMeta

Source: https://encore.dev/docs/ts/develop/metadata

Shows how to use appMeta().environment.cloud to select different implementations for different cloud providers. Useful for integrating with services not natively supported by Encore.

```typescript
import { appMeta } from "encore.dev";

// Emit an audit event.
async function audit(userID: string, event: Record<string, any>) {
  const cloud = appMeta().environment.cloud;
  switch (cloud) {
    case "aws":
      return writeIntoRedshift(userID, event);
    case "gcp":
      return writeIntoBigQuery(userID, event);
    case "local":
      return writeIntoFile(userID, event);
    default:
      throw new Error(`unknown cloud: ${cloud}`);
  }
}

```

--------------------------------

### begin() transaction example

Source: https://encore.dev/docs/ts/runtime/storage-sqldb

Begins a database transaction using the await using pattern, which automatically rolls back if neither commit nor rollback is called before the variable goes out of scope.

```typescript
await using tx = await db.begin();
await tx.exec`INSERT INTO ...`;
await tx.commit();
```

--------------------------------

### Create a subscription to the signups topic

Source: https://encore.dev/docs/ts/primitives/pubsub

Creates a subscription to the 'signups' topic with a unique name 'send-welcome-email' and a handler that processes each event. The subscription can be defined in any service and receives events independently of other subscriptions.

```typescript
import { Subscription } from "encore.dev/pubsub";

const _ = new Subscription(signups, "send-welcome-email", {
    handler: async (event) => {
        // Send a welcome email using the event.
    },
});

```

--------------------------------

### Run Encore app locally

Source: https://encore.dev/docs/ts/how-to/nestjs

Run `encore run` in your terminal to start your Encore app locally. You should see log messages about both Encore and Nest starting up.

```bash
$ encore run

```

--------------------------------

### Example directory structure for migrations

Source: https://encore.dev/docs/ts/primitives/databases

Shows the recommended file layout for an Encore service with a migrations directory. The structure includes migration files, service code, and tests.

```plaintext
/my-app
├── encore.app                       // ... other top-level project files
│
└── todo                             // todo service
    ├── migrations                   // database migrations (directory)
    │   ├── 1_create_table.up.sql    // first migration file
    │   └── 2_add_field.up.sql       // second migration file
    ├── todo.ts                      // todo service code
    └── todo.test.ts                 // tests for todo service
```

--------------------------------

### getRange(key, start, end)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Returns a substring of the string value stored at key. The start and end indices are zero-based and inclusive. Negative values can be used for offsets from the end.

```APIDOC
## getRange(key, start, end)

### Description
Returns a substring of the string value stored at key. The `start` and `end` values are zero-based indices, but unlike typical slicing the `end` value is inclusive. Negative values can be used in order to provide an offset starting from the end of the string, so -1 means the last character. If the string does not exist it returns the empty string.

### Method
`getRange(key, start, end): Promise<string>`

### Parameters
- **key** (`K`) - The cache key.
- **start** (`number`) - Start index (inclusive, 0-based).
- **end** (`number`) - End index (inclusive, 0-based). Use -1 for end of string.

### Returns
`Promise<string>` - The substring.

### See
https://redis.io/commands/getrange/
```

--------------------------------

### Log batch completion summary

Source: https://encore.dev/docs/ts/observability/logging

Logs a summary for a batch operation, including total, succeeded, skipped, and failed counts. Use for long-running operations to distinguish started from not started.

```typescript
log.info("user import completed", {
  event: "user_import.completed",
  importId,
  totalCount,
  succeededCount,
  skippedCount,
  failedCount,
  durationMs,
});
```

--------------------------------

### with(options)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Returns a shallow clone of this keyspace with the specified write options applied. This allows setting expiry for a chain of operations.

```APIDOC
## with(options)

### Description
Returns a shallow clone of this keyspace with the specified write options applied. This allows setting expiry for a chain of operations.

### Method
`with`

### Parameters
- **options** (`WriteOptions`) - Required - Write options to apply.

### Returns
`this` - A shallow clone of the keyspace with the options applied.

### Example
`await myKeyspace.with({ expiry: expireIn(5000) }).set(key, value)`
```

--------------------------------

### with(options)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Returns a shallow clone of this keyspace with the specified write options applied. This allows setting expiry for a chain of operations.

```APIDOC
## Method: with(options)

### Description
Returns a shallow clone of this keyspace with the specified write options applied. This allows setting expiry for a chain of operations.

### Parameters
- **options** (`WriteOptions`) - Required - Write options to apply.

### Returns
`this`

### Example
`await myKeyspace.with({ expiry: expireIn(5000) }).set(key, value)`
```

--------------------------------

### getRange(key, start, stop)

Source: https://encore.dev/docs/ts/runtime/storage-cache

Returns the elements in the list stored at key between start and stop (inclusive). Both are zero-based indices. Negative indices can be used to indicate offsets from the end of the list.

```APIDOC
## Method: getRange(key, start, stop)

### Description
Returns the elements in the list stored at key between `start` and `stop` (inclusive). Both are zero-based indices. Negative indices can be used to indicate offsets from the end of the list, where -1 is the last element of the list, -2 the penultimate element, and so on. If the key does not exist it returns an empty array.

### Parameters
- **key** (`K`) - Required - The cache key.
- **start** (`number`) - Required - Start index (inclusive).
- **stop** (`number`) - Required - Stop index (inclusive).

### Returns
`Promise<number[]>` - The elements in the specified range.

### See
https://redis.io/commands/lrange/
```
Tokens:
Raw