Skip to main content

TypeScript Customization

Keep generated domain code replaceable and keep Node infrastructure out of browser packages. Runtime policy, provider resources, identity, and sinks are assembled by the server; the browser can request intent but cannot approve it.

Node context factory​

type TrustedRequest = Readonly<{
  tenantId: bigint;
  actorId: string;
  permissions: ReadonlySet<string>;
}>;

async function requestContext(
  infrastructure: Infrastructure,
  trusted: TrustedRequest,
): Promise<UserContext> {
  const ctx = new UserContext();
  // Register generated metadata, explicit Node provider, policy and audit sinks.
  // Install only authenticated server values.
  return ctx;
}

Use released APIs/export paths after publication. Do not expose provider construction to route bodies and do not pass a service as a second execution argument.

Dynamic input adapter​

Parse unknown input, validate it, then map an allowlisted discriminated union to generated methods:

function applyFilter(req: CustomerOrderRequest, filter: Filter): CustomerOrderRequest {
  switch (`${filter.field}:${filter.operator}`) {
    case "order_number:contains":
      return req.withOrderNumberContaining(requireString(filter.value));
    default:
      throw new InvalidQuery("Unsupported field or operator");
  }
}

Reject unknown/deep paths, excessive IN/page size, reversed or wrongly typed ranges, negative offset and forbidden sort. Derive rows, count, totals, and facets from one normalized filter.

Policy, behavior, and audit​

Entity-local invariants belong in generated behavior/checker contracts. Tenant scope, permissions, approved purpose and platform limits belong in context request policy. Every mutation uses auditAs; the immutable runtime mutation event and separately registered masked application event are distinct evidence paths.

Provider exports​

Import SQL providers only through documented Node subpaths. Keep the root/browser export free of native modules and Node built-ins. Qualify each provider with real persistence, reconnect, optimistic locking, aggregates, pagination, and relation Top-N.

Federal customization​

Customize endpoint discovery, authentication transport, retry and tracing around the generated federal protocol client without replacing the protocol with arbitrary HTTP. The backend rebuilds trusted UserContext, validates the query allowlist, and decides whether requested purpose is approved.

Packaging after release​

Pin official npm packages and preserve the lock file. Test Node ESM/CJS behavior and a clean browser bundle against the documented exports. Until package coordinates are announced, leave installation commands unfilled rather than naming a local cache or preview tarball as a release.

If a change requires editing generated Q, Request, Entity, or expression source, fix KSML, generator, or runtime and regenerate.