stratal-framework

Category: Tools & Productivity | Uploader: strataljs | Downloads: 0 | Version: v1.0（Latest）
Changelog: Source: GitHub https://github.com/strataljs/stratal
Directory Structure

Current level: .agents/skills/stratal-framework/
📄 SKILL.md 5.9 KB
SKILL.md

---
name: stratal-framework
description: >-
  Use when working with @stratal/framework — authentication (Better Auth), database
  (ZenStack ORM), RBAC (Casbin), AuthGuard, and test data factories. Trigger on:
  auth, AuthModule, AuthService, AuthContext, AuthGuard, Better Auth, database,
  DatabaseModule, DatabaseService, @InjectDB, ZenStack, RBAC, RbacModule,
  CasbinService, Casbin, Factory, Sequence, @stratal/framework,
  multi-connection, per-connection schemas.
user-invocable: false
license: MIT
metadata:
  author: Temitayo Fadojutimi
  version: "3.0"
---

# @stratal/framework

Higher-level framework modules for Stratal: authentication (Better Auth), database ORM (ZenStack), RBAC (Casbin), authorization guards, and test data factories. Full documentation at [stratal.dev/framework](https://stratal.dev/framework/overview).

## Authentication (AuthModule)

Docs: [Auth](https://stratal.dev/framework/auth)

```ts
@Module({
  imports: [
    AuthModule.forRootAsync({
      inject: [authConfig.KEY],
      useFactory: (config) => ({
        secret: config.secret,
        baseURL: config.baseURL,
        // ...Better Auth options
      }),
    }),
  ],
})
export class AppModule {}
```

`AuthContext` is request-scoped and available via `@inject(DI_TOKENS.AuthContext)`. Key methods: `isAuthenticated()`, `getUserId()`, `requireUserId()`, `getAuthContext()`. AuthModule auto-registers session verification middleware.

## Database (DatabaseModule)

Docs: [Database](https://stratal.dev/framework/database) · [Database Events](https://stratal.dev/framework/database-events)

Each connection brings its own ZenStack schema. Users write per-connection `.zmodel` files, run `zenstack generate` independently, and pass each connection's schema in the config.

```ts
import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { Pool } from 'pg';
import { schema } from '../db/main/schema';

DatabaseModule.forRootAsync({
  inject: [DI_TOKENS.CloudflareEnv],
  useFactory: (env: StratalEnv) => ({
    default: 'main',
    connections: [
      {
        name: 'main',
        schema,
        dialect: () => new PostgresDialect({
          pool: new Pool({ connectionString: env.DB.connectionString, max: 1 }),
        }),
      },
    ],
  }),
})
```

**Type augmentation:**

```ts
declare module '@stratal/framework/database' {
  interface StratalDatabase {
    schemas: {
      main: MainSchemaType;
      analytics: AnalyticsSchemaType;
    };
    defaultConnection: 'main';
  }
}
```

Inject with `@inject(DI_TOKENS.Database)` (default connection) or `@InjectDB('name')` (named). Plugins: `EventEmitterPlugin`, `SchemaSwitcherPlugin`, `ErrorHandlerPlugin`.

**Database events** follow the pattern `{phase}.{Model}.{operation}` — e.g., `after.User.create`. Augment `CustomEventRegistry` with `DatabaseEvents<ConnectionName>` for type safety.

### Multi-Connection Per-Connection Schemas

Each connection has its own `.zmodel` file and its own `zenstack generate` output. For shared models, use ZenStack's native `import`/`extends` between schema files.

**Per-connection schema setup:**

```
db/
  main/
    schema.zmodel      # Main connection models
    schema.ts          # Generated by zenstack generate
  analytics/
    schema.zmodel      # Analytics connection models
    schema.ts          # Generated by zenstack generate
```

**Config with per-connection schemas:**

```ts
import { schema as mainSchema } from '../db/main/schema';
import { schema as analyticsSchema } from '../db/analytics/schema';

DatabaseModule.forRootAsync({
  inject: [DI_TOKENS.CloudflareEnv],
  useFactory: (env: StratalEnv) => ({
    default: 'main',
    connections: [
      { name: 'main', schema: mainSchema, dialect: () => ... },
      { name: 'analytics', schema: analyticsSchema, dialect: () => ... },
    ],
  }),
})
```

**Migrations** — use standard ZenStack commands per connection:

```bash
zenstack db push --schema db/main/schema.zmodel
zenstack db push --schema db/analytics/schema.zmodel
```

## RBAC (RbacModule)

Docs: [RBAC](https://stratal.dev/framework/rbac)

```ts
RbacModule.forRoot({
  model: casbinModel,
  defaultPolicies: [['admin', 'users:*', '.*']],
  roleHierarchy: [['super_admin', 'admin']],
})
```

`CasbinService` is request-scoped. Key methods: `hasPermission()`, `currentUserHasPermission()`, `hasAnyPermission()`, `currentUserHasAnyPermission()`, `addRoleForUser()`, `getRolesForUser()`, `getCurrentUserRoles()`. Requires a `CasbinRule` model in your ZenStack schema.

## AuthGuard

Docs: [AuthGuard](https://stratal.dev/framework/auth-guard)

```ts
// Auth only — checks isAuthenticated()
@UseGuards(AuthGuard())

// Auth + permissions — checks isAuthenticated() + CasbinService
@UseGuards(AuthGuard({ scopes: ['users:read'] }))
```

Throws `UserNotAuthenticatedError` (401) or `InsufficientPermissionsError` (403). Apply at class or method level.

## Test Factories

Docs: [Factories](https://stratal.dev/testing/factories)

```ts
export class UserFactory extends Factory<User, UserCreateInput> {
  protected model = 'user';
  protected definition() {
    return {
      email: this.faker.internet.email(),
      name: this.faker.person.fullName(),
    };
  }
  admin() {
    return this.state((attrs) => ({ ...attrs, role: 'admin' }));
  }
}
```

```ts
// Usage
const user = await new UserFactory().create(db);
const admins = await new UserFactory().admin().count(5).createManyAndReturn(db);
```

Methods: `make()` (build without saving), `create()` (persist), `makeMany()`, `createMany()`, `createManyAndReturn()`. Use `state()` for variants and `count()` for batch creation.

## Sub-path Imports

| Path | Key Exports |
|---|---|
| `@stratal/framework/auth` | `AuthModule`, `AuthService`, `AuthContext` |
| `@stratal/framework/database` | `DatabaseModule`, `DatabaseService`, `@InjectDB`, `databaseI18n` |
| `@stratal/framework/rbac` | `RbacModule`, `CasbinService` |
| `@stratal/framework/guards` | `AuthGuard` |
| `@stratal/framework/factory` | `Factory`, `Sequence` |
| `@stratal/framework/context` | `RequestContext` |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
stratal-framework

Directory Structure

SKILL.md

Report

Notice
