@bishop-and-co/dmvc

██████╗   ███╗   ███╗ ██╗     ██╗  ██████╗ 
██╔══██╗  ████╗ ████║ ██║     ██║ ██╔════╝ 
██║  ██║  ██╔████╔██║ ██║     ██║ ██║           
██║  ██║  ██║╚██╔╝██║ ╚██╗   ██╔╝ ██║           
██████╔╝  ██║ ╚═╝ ██║  ╚██████╔╝  ╚██████╗ 
╚═════╝   ╚═╝     ╚═╝   ╚═════╝    ╚═════╝ 

dmvc

dmvc provides a minimal model/controller layer for building REST APIs on top of Hono. It pairs ElectroDB for DynamoDB access with Zod schemas and exposes helpers to quickly register CRUD routes.

Install via npm i @bishop-and-co/dmvc. Source code is available on GitHub.

Installation

hono is a peer dependency and must be installed in your application along with DMVC's runtime dependencies:

npm install @bishop-and-co/dmvc hono zod electrodb @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Defining a model

Create a model by extending BaseModel. ElectroDB conventions use the model name itself as the identifier attribute, so avoid generic id or modelId fields. The model wires up a Zod schema and ElectroDB entity:

import { BaseModel } from "@bishop-and-co/dmvc";
import { Entity } from "electrodb";
import { z } from "zod";

const UserSchema = z.object({
  user: z.string(), // model id
  name: z.string().optional(),
});

export class UserModel extends BaseModel<typeof UserSchema> {
  constructor(client: any, table: string) {
    super(client, table);
    this.schema = UserSchema;
    this.keySchema = UserSchema.pick({ user: true });
    this.entity = new Entity(
      {
        model: { entity: "User", version: "1", service: "app" },
        attributes: { user: { type: "string", required: true }, name: { type: "string" } },
        indexes: { primary: { pk: { field: "pk", composite: ["user"] } } },
      },
      { client, table }
    );
  }
}

Configure the DynamoDB connection once during startup:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { BaseModel } from "@bishop-and-co/dmvc";

const raw = new DynamoDBClient({ region: "us-east-1" });
const client = DynamoDBDocumentClient.from(raw);
BaseModel.configure({ client, table: process.env.DYNAMODB_TABLE_NAME! });

Registering routes

Use BaseController.register to expose CRUD endpoints for the model:

import { Hono } from "hono";
import { BaseController, requireAuth } from "@bishop-and-co/dmvc";
import { UserModel } from "./UserModel";

const app = new Hono();

BaseController.register(app, {
  model: UserModel,
  basePath: "/users",
});

export default app;

You can optionally supply per-operation roles, a custom authCheckFn, or pageSize in the options.

Authentication

dmvc expects an authenticated user to be attached to the Hono context as c.set("user", ...).
Routes registered through BaseController automatically use the requireAuth middleware which checks the user's role, supports a custom checker, and honours the SKIP_AUTH environment flag and the special anonymous role.

import { Hono } from "hono";
import { BaseController, requireAuth } from "@bishop-and-co/dmvc";
import { UserModel } from "./UserModel";

const app = new Hono();

// attach a user from your auth system (JWT, session, etc.)
app.use("*", async (c, next) => {
  const token = c.req.header("Authorization");
  if (token) {
    // decode token and set the user on the context
    c.set("user", { user: "u123", role: "admin" });
  }
  await next();
});

// optional custom authorization function
const authCheckFn = async (user: any, allowed: string[]) => {
  if (user.role === "admin") return true; // admins always allowed
  return allowed.includes(user.role);
};

BaseController.register(app, {
  model: UserModel,
  basePath: "/users",
  roles: {
    list: ["anonymous"],   // public route
    get: ["user", "admin"],
    create: ["admin"],
    update: ["admin"],
    delete: ["admin"],
  },
  authCheckFn,
});

app.get(
  "/reports",
  requireAuth(["admin"], authCheckFn),
  (c) => c.text("secret")
);

Set SKIP_AUTH=true in the environment to bypass all checks during local development.

Hooks

BaseModel supports lifecycle hooks via decorators:

import { BeforeCreate, AfterDelete } from "@bishop-and-co/dmvc";

class UserModel extends BaseModel<typeof UserSchema> {
  @BeforeCreate
  async setDefaults(data: any) {
    data.createdAt = new Date().toISOString();
  }

  @AfterDelete
  async logDeletion(deleted: any) {
    console.log("deleted", deleted);
  }
}

These hooks run automatically around the respective operations.

Generator

dmvc ships with a tiny CLI that scaffolds boilerplate models and controllers for you.

npx dmvc generate model widget
# => creates src/models/Widget.ts

npx dmvc generate controller widget
# => creates src/controllers/WidgetController.ts

The generator creates the src/models and src/controllers directories if they do not exist and refuses to overwrite existing files. Edit the generated files to flesh out schemas, attributes, and any custom logic for your application.

On first run, the generator asks where to place models and controllers and writes a dmvc.config.ts file with your answers. You can adjust this file later:

export default {
  modelFolder: 'app/models',
  controllerFolder: 'app/controllers',
};

The generator will respect these paths when creating new files.

Example

A minimal todo application built with dmvc lives in examples/todo. It defines a todo model and registers CRUD routes with Hono. The example's package.json also exposes scripts to create, read, update, and destroy todos, and includes a docker-compose.yml for spinning up a local DynamoDB instance. See its README for setup instructions.

dmvc aims to stay minimal. See the source for additional helpers like requireAuth and QueryService.