mkdir typesense-data
# Start Typesense
docker run -d -p 8108:8108 \
-v "$(pwd)"/typesense-data:/data \
typesense/typesense:{{ $site.themeConfig.typesenseLatestVersion }} \
--data-dir /data \
--api-key=xyz \
--enable-cors
# Start PostgreSQL
docker run -d -p 5432:5432 \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=testdb \
postgres:16
## Step 2: Initialize your Deno project
Create the project and add dependencies:
```bash
mkdir typesense-deno-hono-search-app
cd typesense-deno-hono-search-app
deno add jsr:@hono/hono npm:postgres npm:typesense
```
What each dependency does:
- **@hono/hono** - Small, fast web framework that runs on `Deno.serve`
- **postgres** - PostgreSQL client for JavaScript, used here with hand-written SQL
- **typesense** - Official Typesense client
Deno has no bundler or build step, so there is no `tsconfig.json` to generate. Instead, define the tasks you'll use in `deno.json`:
```json
{
"tasks": {
"dev": "deno run --allow-net --allow-env --allow-read --allow-sys --env-file=.env --watch src/server.ts",
"start": "deno run --allow-net --allow-env --allow-read --allow-sys --env-file=.env src/server.ts",
"db:migrate": "deno run --allow-net --allow-env --allow-read --allow-sys --env-file=.env src/migrate.ts"
},
"imports": {
"hono": "jsr:@hono/hono@^4.13.4",
"hono/cors": "jsr:@hono/hono@^4.13.4/cors",
"postgres": "npm:postgres@^3.4.9",
"typesense": "npm:typesense@^3.0.6"
},
"compilerOptions": {
"strict": true
},
"nodeModulesDir": "auto"
}
```
The `--env-file` flag is built into Deno, so no dotenv package is needed.
## Step 3: Create the project structure
```plaintext
typesense-deno-hono-search-app/
├── db/
│ └── schema.sql # Table, indexes, and updated_at trigger
├── src/
│ ├── config/
│ │ ├── database.ts # postgres.js connection pool
│ │ └── env.ts # Environment variable validation
│ ├── db/
│ │ └── books.ts # SQL queries for the books table
│ ├── routes/
│ │ ├── books.ts # CRUD API handlers
│ │ └── search.ts # Search API handlers
│ ├── search/
│ │ ├── client.ts # Typesense client initialization
│ │ ├── collections.ts # Typesense collection schema
│ │ ├── sync.ts # DB → Typesense sync logic
│ │ └── worker.ts # Background sync interval
│ ├── migrate.ts # Applies db/schema.sql
│ └── server.ts # Application entry point
├── deno.json
└── .env
```
## Step 4: Set up environment configuration
Create your `.env` file:
```bash
PORT=3000
DATABASE_URL=postgres://postgres:password@localhost:5432/testdb
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz
TYPESENSE_COLLECTION=books
SYNC_INTERVAL_SECONDS=60
SYNC_BATCH_SIZE=1000
```
Create `src/config/env.ts` to safely parse and export these environment variables:
```typescript
const REQUIRED = [
'DATABASE_URL',
'TYPESENSE_HOST',
'TYPESENSE_PORT',
'TYPESENSE_PROTOCOL',
'TYPESENSE_API_KEY',
'TYPESENSE_COLLECTION',
] as const;
for (const key of REQUIRED) {
if (!Deno.env.get(key)) {
throw new Error(`Missing required environment variable: ${key}`);
}
}
const number = (key: string, fallback: number): number => {
const raw = Deno.env.get(key);
if (!raw) return fallback;
const parsed = Number(raw);
if (!Number.isFinite(parsed)) throw new Error(`Environment variable ${key} must be a number`);
return parsed;
};
export const env = {
PORT: number('PORT', 3000),
DATABASE_URL: Deno.env.get('DATABASE_URL')!,
TYPESENSE_HOST: Deno.env.get('TYPESENSE_HOST')!,
TYPESENSE_PORT: number('TYPESENSE_PORT', 8108),
TYPESENSE_PROTOCOL: Deno.env.get('TYPESENSE_PROTOCOL')!,
TYPESENSE_API_KEY: Deno.env.get('TYPESENSE_API_KEY')!,
TYPESENSE_COLLECTION: Deno.env.get('TYPESENSE_COLLECTION')!,
SYNC_INTERVAL_SECONDS: number('SYNC_INTERVAL_SECONDS', 60),
SYNC_BATCH_SIZE: number('SYNC_BATCH_SIZE', 1000),
};
```
Create `src/config/database.ts` to initialize the connection pool:
```typescript
import postgres from 'postgres';
import { env } from './env.ts';
export const sql = postgres(env.DATABASE_URL, {
max: 10,
onnotice: (notice) => console.log(`postgres notice: ${notice.message}`),
});
```
## Step 5: Define the Database Schema and Queries
Define your `books` table in `db/schema.sql`:
```sql
CREATE TABLE IF NOT EXISTS books (
id SERIAL PRIMARY KEY,
title VARCHAR(255) NOT NULL,
authors TEXT[] NOT NULL DEFAULT '{}',
publication_year INTEGER,
average_rating NUMERIC(3, 2),
image_url VARCHAR(512),
ratings_count INTEGER NOT NULL DEFAULT 0,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
deleted_at TIMESTAMPTZ
);
CREATE INDEX IF NOT EXISTS books_updated_at_idx ON books (updated_at);
CREATE INDEX IF NOT EXISTS books_deleted_at_idx ON books (deleted_at);
CREATE INDEX IF NOT EXISTS books_active_id_idx ON books (id) WHERE deleted_at IS NULL;
CREATE OR REPLACE FUNCTION books_touch_updated_at() RETURNS trigger AS $$
BEGIN
NEW.updated_at = now();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
DROP TRIGGER IF EXISTS books_touch_updated_at ON books;
CREATE TRIGGER books_touch_updated_at
BEFORE UPDATE ON books
FOR EACH ROW
EXECUTE FUNCTION books_touch_updated_at();
```
The trigger maintains `updated_at` in the database rather than in application code, so rows changed outside this API are still picked up by the incremental sync in Step 8.
Create `src/migrate.ts` to apply the schema:
```typescript
import { sql } from './config/database.ts';
const schemaPath = new URL('../db/schema.sql', import.meta.url);
const ddl = await Deno.readTextFile(schemaPath);
console.log('Applying db/schema.sql...');
try {
await sql.unsafe(ddl).simple();
console.log('Schema applied successfully.');
} catch (error) {
console.error('Migration failed:', error);
Deno.exit(1);
} finally {
await sql.end();
}
```
`.simple()` selects the simple query protocol, which allows several statements in one round trip, including the `$$ ... $$` function body.
Push the schema to the database:
```bash
deno task db:migrate
```
Now add the queries in `src/db/books.ts`. The last three are used by the sync, and all paginate by `id` rather than `OFFSET`:
```typescript
import { sql } from '../config/database.ts';
export interface Book {
id: number;
title: string;
authors: string[];
publication_year: number | null;
average_rating: string | null;
image_url: string | null;
ratings_count: number;
created_at: Date;
updated_at: Date;
deleted_at: Date | null;
}
export interface BookInput {
title?: string;
authors?: string[];
publication_year?: number | null;
average_rating?: number | null;
image_url?: string | null;
ratings_count?: number;
}
export async function dbNow(): Promise