@stratal/inertia 0.0.1

package/README.md

@@ -0,0 +1,91 @@
+# @stratal/inertia
+
+Inertia.js v3 server adapter for [Stratal](https://github.com/strataljs/stratal) framework — build server-driven React SPAs on Cloudflare Workers.
+
+[![npm version](https://img.shields.io/npm/v/@stratal/inertia)](https://www.npmjs.com/package/@stratal/inertia)
+[![CI](https://github.com/strataljs/stratal/actions/workflows/ci.yml/badge.svg)](https://github.com/strataljs/stratal/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/strataljs/stratal/badge)](https://securityscorecards.dev/viewer/?uri=github.com/strataljs/stratal)
+[![Known Vulnerabilities](https://snyk.io/test/github/strataljs/stratal/badge.svg)](https://snyk.io/test/github/strataljs/stratal)
+[![npm downloads](https://img.shields.io/npm/dm/@stratal/inertia)](https://www.npmjs.com/package/@stratal/inertia)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@stratal/inertia)](https://bundlephobia.com/package/@stratal/inertia)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/strataljs/stratal/pulls)
+[![GitHub stars](https://img.shields.io/github/stars/strataljs/stratal?style=social)](https://github.com/strataljs/stratal)
+
+## Features
+
+- **InertiaModule** — Drop-in Stratal module with `forRoot()` / `forRootAsync()` configuration
+- **Server-Side Rendering** — SSR support with configurable per-route disabling
+- **Shared Data** — Global shared props with static values or request-scoped resolvers
+- **@InertiaRoute Decorator** — Convention-based Inertia page routes with auto-applied response schema
+- **Partial Reloads** — Optional, deferred, and merge props for efficient data loading
+- **Quarry CLI Commands** — `inertia:install`, `inertia:dev`, `inertia:build`, and `inertia:types`
+
+## Installation
+
+```bash
+npm install @stratal/inertia
+# or
+yarn add @stratal/inertia
+```
+
+### AI Agent Skills
+
+Stratal provides [Agent Skills](https://agentskills.io) for AI coding assistants like Claude Code and Cursor. Install to give your AI agent knowledge of Stratal patterns, conventions, and APIs:
+
+```bash
+npx skills add strataljs/stratal
+```
+
+| Skill | Description |
+|---|---|
+| `stratal` | Build Cloudflare Workers apps with the Stratal framework — modules, DI, controllers, routing, OpenAPI, queues, cron, events, seeders, CLI, auth, database, RBAC, testing, and more |
+
+## Quick Start
+
+### Module setup
+
+```typescript
+import { Stratal } from 'stratal'
+import { Module } from 'stratal/module'
+import { InertiaModule } from '@stratal/inertia'
+
+@Module({
+  imports: [
+    InertiaModule.forRoot({
+      rootView: 'app',
+      entryClientPath: 'src/inertia/app.tsx',
+      sharedData: {
+        appName: 'My App',
+      },
+    }),
+  ],
+})
+class AppModule {}
+
+export default new Stratal({ module: AppModule })
+```
+
+### Controller with @InertiaRoute
+
+```typescript
+import { Controller, type RouterContext } from 'stratal/router'
+import { InertiaRoute } from '@stratal/inertia'
+
+@Controller('/notes')
+export class NotesController {
+  @InertiaRoute({ summary: 'List notes' })
+  async index(ctx: RouterContext) {
+    return ctx.inertia('notes/Index', { notes: [] })
+  }
+}
+```
+
+## Documentation
+
+Full guides and examples are available at **[stratal.dev](https://stratal.dev)**.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,259 @@
+/// <reference path="../global.d.ts" />
+import { AsyncModuleOptions, DynamicModule, OnInitialize } from "stratal/module";
+import { Middleware, RouteConfig, RouterContext } from "stratal/router";
+import { Command } from "stratal/quarry";
+import { z } from "stratal/validation";
+import { MiddlewareConfigurable, MiddlewareConsumer } from "stratal/middleware";
+import { SharedPageProps } from "@inertiajs/core";
+
+//#region src/types.d.ts
+interface InertiaPageRegistry {}
+type InertiaSharedProps = SharedPageProps;
+type InertiaPageComponent = keyof InertiaPageRegistry extends never ? string : Extract<keyof InertiaPageRegistry, string>;
+type AllowInertiaWrappers<T> = { [K in keyof T]: T[K] | InertiaDeferredProp | InertiaMergeProp | InertiaOptionalProp };
+type ResolvedInertiaPageProps<C extends InertiaPageComponent> = C extends keyof InertiaPageRegistry ? AllowInertiaWrappers<InertiaPageRegistry[C]> : Record<string, unknown>;
+type InertiaFullPageProps<C extends InertiaPageComponent> = (C extends keyof InertiaPageRegistry ? InertiaPageRegistry[C] : Record<string, unknown>) & InertiaSharedProps;
+interface InertiaPage {
+  component: string;
+  props: Record<string, unknown>;
+  url: string;
+  version: string;
+  mergeProps: string[];
+  deferredProps: Record<string, string[]>;
+  encryptHistory?: boolean;
+  clearHistory?: boolean;
+}
+interface InertiaRenderOptions {
+  encryptHistory?: boolean;
+  clearHistory?: boolean;
+}
+interface InertiaSsrResult {
+  head: string[];
+  body: string;
+}
+interface InertiaSsrBundle {
+  render(page: InertiaPage): Promise<InertiaSsrResult>;
+}
+type SharedDataResolver = (ctx: RouterContext) => any;
+interface ViteManifestEntry {
+  file: string;
+  css?: string[];
+  isEntry?: boolean;
+  imports?: string[];
+  dynamicImports?: string[];
+  src?: string;
+}
+type ViteManifest = Record<string, ViteManifestEntry>;
+declare const INERTIA_PROP_OPTIONAL: unique symbol;
+declare const INERTIA_PROP_DEFERRED: unique symbol;
+declare const INERTIA_PROP_MERGE: unique symbol;
+interface InertiaOptionalProp {
+  [INERTIA_PROP_OPTIONAL]: true;
+  callback: () => unknown;
+}
+interface InertiaDeferredProp {
+  [INERTIA_PROP_DEFERRED]: true;
+  callback: () => unknown;
+  group: string;
+}
+interface InertiaMergeProp {
+  [INERTIA_PROP_MERGE]: true;
+  callback: () => unknown;
+}
+//#endregion
+//#region src/inertia.options.d.ts
+interface SsrBundleModule {
+  render(page: InertiaPage): Promise<InertiaSsrResult>;
+}
+interface InertiaSsrOptions {
+  bundle: () => Promise<SsrBundleModule | {
+    default: SsrBundleModule;
+  }>;
+  /**
+   * Route patterns where SSR is disabled (e.g., `"admin/*"`).
+   * Uses simple glob matching against the request pathname.
+   */
+  disabled?: string[];
+}
+interface InertiaModuleOptions {
+  rootView: string;
+  version?: string;
+  ssr?: InertiaSsrOptions;
+  sharedData?: Record<string, unknown>;
+  /**
+   * Vite manifest for production builds. When omitted, dev mode is assumed
+   * and Vite client + entry scripts are injected with same-origin paths.
+   */
+  manifest?: ViteManifest;
+  /**
+   * Client entry path relative to project root (default: `src/inertia/app.tsx`).
+   * Used in dev mode to inject the entry script tag.
+   */
+  entryClientPath?: string;
+}
+//#endregion
+//#region src/inertia.module.d.ts
+declare class InertiaModule implements MiddlewareConfigurable, OnInitialize {
+  static forRoot(options: InertiaModuleOptions): DynamicModule;
+  static forRootAsync(options: AsyncModuleOptions<InertiaModuleOptions>): DynamicModule;
+  configure(consumer: MiddlewareConsumer): void;
+  onInitialize(): void;
+}
+//#endregion
+//#region src/inertia.tokens.d.ts
+declare const INERTIA_TOKENS: {
+  readonly Options: symbol;
+  readonly InertiaService: symbol;
+  readonly TemplateService: symbol;
+  readonly ManifestService: symbol;
+  readonly SsrRenderer: symbol;
+};
+//#endregion
+//#region src/services/ssr-renderer.service.d.ts
+declare class SsrRendererService {
+  private readonly options;
+  private bundle;
+  private loadPromise;
+  constructor(options: InertiaModuleOptions);
+  render(page: InertiaPage): Promise<InertiaSsrResult>;
+  private ensureBundle;
+  private loadBundle;
+}
+//#endregion
+//#region src/services/manifest.service.d.ts
+declare class ManifestService {
+  private readonly manifest;
+  private readonly entryClientPath;
+  constructor(options: InertiaModuleOptions);
+  private get isDev();
+  getHeadTags(): string;
+  getScriptTags(): string;
+}
+//#endregion
+//#region src/services/template.service.d.ts
+declare class TemplateService {
+  private readonly options;
+  private readonly manifest;
+  constructor(options: InertiaModuleOptions, manifest: ManifestService);
+  render(page: InertiaPage, ssrHead: string[], ssrBody: string): string;
+  private buildClientOnlyBody;
+}
+//#endregion
+//#region src/services/inertia.service.d.ts
+declare class InertiaService {
+  private readonly options;
+  private readonly template;
+  private readonly ssr;
+  private sharedData;
+  constructor(options: InertiaModuleOptions, template: TemplateService, ssr: SsrRendererService);
+  share(key: string, value: unknown): void;
+  location(url: string): Response;
+  optional(callback: () => unknown): InertiaOptionalProp;
+  defer(callback: () => unknown, group?: string): InertiaDeferredProp;
+  merge(callback: () => unknown): InertiaMergeProp;
+  render(ctx: RouterContext, component: string, props?: Record<string, unknown>, renderOptions?: InertiaRenderOptions): Promise<Response>;
+  private resolveSharedData;
+  private processProps;
+  /**
+   * Check if a prop key is requested — supports dot-notation (e.g., `user.permissions`
+   * matches the top-level `user` key).
+   */
+  private isRequested;
+  private isOptionalProp;
+  private isDeferredProp;
+  private isMergeProp;
+  private isSsrDisabled;
+}
+//#endregion
+//#region src/decorators/inertia-route.decorator.d.ts
+type InertiaRouteConfig = Omit<RouteConfig, 'response' | 'statusCode' | 'hideFromDocs'> & {
+  hideFromDocs?: boolean;
+};
+/**
+ * Decorator for Inertia page routes.
+ *
+ * Wraps `@Route()` with:
+ * - Auto-applied Inertia page response schema
+ * - `hideFromDocs: true` by default (overridable)
+ *
+ * Accepts `query`, `params`, `body`, `tags`, `summary`, `description`, `security`.
+ *
+ * @example
+ * ```typescript
+ * @Controller('/notes')
+ * export class NotesController implements IController {
+ *   @InertiaRoute({ query: z.object({ page: z.string().optional() }) })
+ *   async index(ctx: RouterContext) {
+ *     return ctx.inertia('notes/Index', { notes: [] })
+ *   }
+ * }
+ * ```
+ */
+declare function InertiaRoute(config?: InertiaRouteConfig): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+//#endregion
+//#region src/middleware/inertia.middleware.d.ts
+declare class InertiaMiddleware implements Middleware {
+  private readonly options;
+  constructor(options: InertiaModuleOptions);
+  handle(ctx: RouterContext, next: () => Promise<void>): Promise<void>;
+}
+//#endregion
+//#region src/commands/inertia-build.command.d.ts
+declare class InertiaBuildCommand extends Command {
+  static command: string;
+  static description: string;
+  handle(): Promise<number | undefined>;
+}
+//#endregion
+//#region src/commands/inertia-dev.command.d.ts
+declare class InertiaDevCommand extends Command {
+  static command: string;
+  static description: string;
+  handle(): Promise<number | undefined>;
+}
+//#endregion
+//#region src/commands/inertia-install.command.d.ts
+declare class InertiaInstallCommand extends Command {
+  static command: string;
+  static description: string;
+  handle(): Promise<number | undefined>;
+  private updateAppModule;
+}
+//#endregion
+//#region src/commands/inertia-types.command.d.ts
+declare class InertiaTypesCommand extends Command {
+  static command: string;
+  static description: string;
+  handle(): Promise<number | undefined>;
+  private generate;
+  private watchForChanges;
+}
+//#endregion
+//#region src/generator/type-generator.d.ts
+declare function runTypeGeneration(cwd: string): Promise<{
+  outputPath: string;
+  pageCount: number;
+}>;
+//#endregion
+//#region src/augment/router-context.d.ts
+declare module 'stratal/router' {
+  interface RouterContext {
+    inertia<C extends InertiaPageComponent>(component: C, ...args: keyof InertiaPageRegistry extends never ? [props?: Record<string, unknown>, options?: InertiaRenderOptions] : Record<string, never> extends ResolvedInertiaPageProps<C> ? [props?: ResolvedInertiaPageProps<C>, options?: InertiaRenderOptions] : [props: ResolvedInertiaPageProps<C>, options?: InertiaRenderOptions]): Promise<Response>;
+    defer(callback: () => unknown, group?: string): InertiaDeferredProp;
+    optional(callback: () => unknown): InertiaOptionalProp;
+    merge(callback: () => unknown): InertiaMergeProp;
+    withoutSsr(): void;
+  }
+}
+//#endregion
+//#region src/augment/router-variables.d.ts
+declare module 'stratal/router' {
+  interface RouterVariables {
+    inertia: boolean;
+    inertiaPrefetch: boolean;
+    withoutSsr: boolean;
+  }
+}
+//#endregion
+export { INERTIA_TOKENS, InertiaBuildCommand, type InertiaDeferredProp, InertiaDevCommand, type InertiaFullPageProps, InertiaInstallCommand, type InertiaMergeProp, InertiaMiddleware, InertiaModule, type InertiaModuleOptions, type InertiaOptionalProp, type InertiaPage, type InertiaPageComponent, type InertiaPageRegistry, type InertiaRenderOptions, InertiaRoute, type InertiaRouteConfig, InertiaService, type InertiaSharedProps, type InertiaSsrBundle, type InertiaSsrOptions, type InertiaSsrResult, InertiaTypesCommand, ManifestService, type ResolvedInertiaPageProps, type SharedDataResolver, SsrRendererService, TemplateService, type ViteManifest, type ViteManifestEntry, runTypeGeneration };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/inertia.options.ts","../src/inertia.module.ts","../src/inertia.tokens.ts","../src/services/ssr-renderer.service.ts","../src/services/manifest.service.ts","../src/services/template.service.ts","../src/services/inertia.service.ts","../src/decorators/inertia-route.decorator.ts","../src/middleware/inertia.middleware.ts","../src/commands/inertia-build.command.ts","../src/commands/inertia-dev.command.ts","../src/commands/inertia-install.command.ts","../src/commands/inertia-types.command.ts","../src/generator/type-generator.ts","../src/augment/router-context.ts","../src/augment/router-variables.ts"],"mappings":"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"}