Skip to content

@saif/platform-typespec

A TypeSpec library that provides Forge's SAIF.Platform conventions: operation templates, status-code models, auth helpers, and eventing models for describing service contracts. It compiles to a .tsp library (lib/main.tsp), not a runtime JS package — unlike @saif/platform and @saif/platform-react, its audience is people authoring TypeSpec service specifications, not app developers importing a JS module.

Forge's saif-feature-api and saif-event-service templates already generate main.tsp files in this vocabulary (ResourceRead<T>, Scopes<[...]> | Roles<[...]>, MockingServer), so most consumers meet this library through generated code before they meet it here.

What it provides

  • Operation templates (lib/operations/) — ResourceRead, ResourceList, and create/update/delete/action variants. The error union varies by template: instance-scoped operations that can 404 (ResourceRead, ResourcePartialUpdate, ResourceCreateOrReplace, most actions) default to BadRequest | NotFound | AuthErrors | ServerError, while collection-scoped operations that cannot (ResourceList, ResourceCreate, ResourceDelete) default to BadRequest | AuthErrors | ServerError (no NotFound).
  • Status-code models (lib/status-codes/) — success, redirection, client-error, and server-error response models.
  • Auth helpers (lib/openapi/) — Scopes<> / Roles<> decorators and OAuth/mock-server definitions (oauth.tsp, server.tsp).
  • Eventing (lib/eventing/) — models for event-based service contracts.

Getting started

Add the package as a dependency and import it from your .tsp entry point (this is already wired for you if your service came from a Forge template):

import "@saif/platform-typespec";

using SAIF.Platform;

Then use the conventions in your spec, for example:

@useAuth(Scopes<["access"]> | Roles<["App.Read"]>)
namespace MyService;

interface Widgets {
  get is ResourceRead<Widget>;
}

Linting

The package ships a @typespec/library-linter integration (src/linter.ts) that other TypeSpec libraries can compile against to catch usage mistakes. Opt in by compiling with the linter import, as the build:tsp script in this package does:

tsp compile . --warn-as-error --import @typespec/library-linter --no-emit

The linter's rule set is currently empty (rules: []) — the integration exists as a placeholder for future Forge-specific rules (for example, enforcing the standard error unions), not as an active check today.

View source on GitHub