@stone-js/starters 0.8.10 → 0.8.12

package/basic-react-native-declarative/adapter/NativeAdapter.ts

@@ -1,108 +0,0 @@
-import { RawResponseWrapper } from './RawResponseWrapper'
-import { NativeAdapterContext, NativeResponse, RawNativeResponseOptions } from './declarations'
-import { NativeEventSource, NativeNavigationEvent, nativeEventSource } from './NativeEventSource'
-import { Adapter, AdapterEventBuilder, AdapterEventHandlerType, IBlueprint } from '@stone-js/core'
-import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
-
-/**
- * Native proof-of-concept adapter for Stone.js.
- *
- * Captures navigation intents from the in-memory event source, normalizes them
- * into `IncomingBrowserEvent` instances, sends them through the kernel and
- * executes the deferred render effect. It is the exact native counterpart of
- * `BrowserAdapter`, with the event source replacing `window`.
- *
- * Temporary by design: it prefigures `@stone-js/react-native-adapter`, which
- * will capture real deep links (`Linking`) and app-state changes on top of the
- * same skeleton.
- */
-export class NativeAdapter extends Adapter<
-NativeNavigationEvent,
-NativeResponse,
-NativeEventSource,
-IncomingBrowserEvent,
-IncomingBrowserEventOptions,
-OutgoingBrowserResponse,
-NativeAdapterContext
-> {
-  private unsubscribe?: () => void
-
-  /**
-   * Creates an instance of the `NativeAdapter`.
-   *
-   * @param blueprint - The application blueprint.
-   * @returns A new instance of `NativeAdapter`.
-   */
-  static create (blueprint: IBlueprint): NativeAdapter {
-    return new this(blueprint)
-  }
-
-  /**
-   * Executes the adapter: subscribes to navigation intents and dispatches the
-   * initial event, exactly like the browser adapter dispatches its synthetic
-   * first navigation on startup.
-   *
-   * Idempotent: running again tears down the previous subscription first.
-   */
-  public async run<ExecutionResultType = undefined>(): Promise<ExecutionResultType> {
-    await this.executeHooks('onStart')
-
-    const eventHandler = this.resolveEventHandler()
-
-    await this.executeEventHandlerHooks('onInit', eventHandler)
-
-    this.unsubscribe?.()
-    this.unsubscribe = nativeEventSource.subscribe((rawEvent) => {
-      void this.eventListener(eventHandler, rawEvent)
-    })
-
-    await this.eventListener(eventHandler, { url: nativeEventSource.initialUrl })
-
-    return undefined as ExecutionResultType
-  }
-
-  /**
-   * Tear down the adapter: remove the navigation subscription and run the
-   * `onStop` hooks. Safe to call multiple times.
-   */
-  public async stop (): Promise<void> {
-    if (this.unsubscribe === undefined) { return }
-    this.unsubscribe()
-    this.unsubscribe = undefined
-    await this.executeHooks('onStop')
-  }
-
-  /**
-   * Processes one navigation intent through the kernel.
-   *
-   * @param eventHandler - The resolved kernel event handler.
-   * @param rawEvent - The raw navigation event.
-   * @returns The platform response.
-   */
-  protected async eventListener (
-    eventHandler: AdapterEventHandlerType<IncomingBrowserEvent, OutgoingBrowserResponse>,
-    rawEvent: NativeNavigationEvent
-  ): Promise<NativeResponse> {
-    const incomingEventBuilder = AdapterEventBuilder.create<IncomingBrowserEventOptions, IncomingBrowserEvent>({
-      resolver: (options) => IncomingBrowserEvent.create(options)
-    })
-
-    const rawResponseBuilder = AdapterEventBuilder.create<RawNativeResponseOptions, RawResponseWrapper>({
-      resolver: (options) => RawResponseWrapper.create(options)
-    })
-
-    const context: NativeAdapterContext = {
-      rawEvent,
-      executionContext: nativeEventSource,
-      rawResponseBuilder,
-      incomingEventBuilder
-    }
-
-    try {
-      return await this.sendEventThroughDestination(context, eventHandler)
-    } catch (error: any) {
-      const builder = await this.handleError(error, context)
-      return await this.buildRawResponse({ ...context, rawResponseBuilder: builder })
-    }
-  }
-}

package/basic-react-native-declarative/adapter/NativeErrorHandler.ts

@@ -1,53 +0,0 @@
-import { emitNativeError } from './renderSink'
-import { NativeResponse } from './declarations'
-import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
-import {
-  ILogger,
-  IBlueprint,
-  LoggerResolver,
-  AdapterErrorContext,
-  IAdapterErrorHandler,
-  defaultLoggerResolver,
-  AdapterEventBuilderType
-} from '@stone-js/core'
-
-/**
- * NativeErrorHandler options.
- */
-export interface NativeErrorHandlerOptions {
-  blueprint: IBlueprint
-}
-
-/**
- * Adapter-level error handler: logs the error and surfaces it on screen
- * through the render sink, so a broken chain is visible instead of silent.
- */
-export class NativeErrorHandler implements IAdapterErrorHandler<NativeNavigationEvent, NativeResponse, NativeEventSource> {
-  private readonly logger: ILogger
-
-  /**
-   * Create a NativeErrorHandler.
-   *
-   * @param options - NativeErrorHandler options.
-   */
-  constructor ({ blueprint }: NativeErrorHandlerOptions) {
-    this.logger = blueprint.get<LoggerResolver>('stone.logger.resolver', defaultLoggerResolver)(blueprint)
-  }
-
-  /**
-   * Handle an error.
-   *
-   * @param error - The error to handle.
-   * @param context - The context of the adapter.
-   * @returns The raw response builder.
-   */
-  public handle (
-    error: Error,
-    context: AdapterErrorContext<NativeNavigationEvent, NativeResponse, NativeEventSource>
-  ): AdapterEventBuilderType<NativeResponse> {
-    this.logger.error(error.message, { error })
-    emitNativeError(error)
-
-    return context.rawResponseBuilder
-  }
-}

package/basic-react-native-declarative/adapter/NativeEventSource.ts

@@ -1,58 +0,0 @@
-/**
- * The native cause captured by the adapter: an intent to show a URL.
- *
- * On a real device this is what a deep link, a push-notification tap or an
- * in-app navigation collapses to. The proof-of-concept models all of them as
- * one tiny in-memory event source; the future `@stone-js/react-native-adapter`
- * will plug `Linking` and `AppState` into the exact same shape.
- */
-export interface NativeNavigationEvent {
-  /** The URL to resolve, e.g. `stone://app/hello/Noowow`. */
-  url: string
-  /** Optional navigation metadata, mirroring the browser's `history.state`. */
-  metadata?: unknown
-}
-
-/**
- * A navigation listener registered by the adapter.
- */
-export type NativeNavigationListener = (event: NativeNavigationEvent) => void
-
-/**
- * The in-memory navigation event source: the native counterpart of `window`
- * for the browser adapter. It is pure JavaScript, so the same code runs under
- * React Native, Node (tests) and anywhere else.
- */
-export class NativeEventSource {
-  /** The synthetic first event, dispatched when the adapter starts. */
-  public readonly initialUrl = 'stone://app/'
-
-  private readonly listeners = new Set<NativeNavigationListener>()
-
-  /**
-   * Register a navigation listener.
-   *
-   * @param listener - The listener to register.
-   * @returns A teardown function removing the listener.
-   */
-  subscribe (listener: NativeNavigationListener): () => void {
-    this.listeners.add(listener)
-    return () => { this.listeners.delete(listener) }
-  }
-
-  /**
-   * Emit a navigation intent, exactly like the router does in the browser
-   * through the `@stonejs/router.navigate` custom event.
-   *
-   * @param url - The URL to navigate to.
-   * @param metadata - Optional navigation metadata.
-   */
-  navigate (url: string, metadata?: unknown): void {
-    this.listeners.forEach((listener) => listener({ url, metadata }))
-  }
-}
-
-/**
- * The application-wide event source instance.
- */
-export const nativeEventSource = new NativeEventSource()

package/basic-react-native-declarative/adapter/RawResponseWrapper.ts

@@ -1,30 +0,0 @@
-import { IRawResponseWrapper } from '@stone-js/core'
-import { NativeResponse, RawNativeResponseOptions } from './declarations'
-
-/**
- * Wraps the raw native response: the platform effect is the deferred `render`
- * closure contributed by the response middleware, executed once the kernel has
- * resolved the outgoing response.
- */
-export class RawResponseWrapper implements IRawResponseWrapper<NativeResponse> {
-  /**
-   * Factory method to create an instance of `RawResponseWrapper`.
-   *
-   * @param options - The raw response options.
-   * @returns A new instance of `RawResponseWrapper`.
-   */
-  static create (options: RawNativeResponseOptions): RawResponseWrapper {
-    return new this(options)
-  }
-
-  private constructor (private readonly options: RawNativeResponseOptions) {}
-
-  /**
-   * Execute the deferred render effect and return its result.
-   *
-   * @returns The platform response.
-   */
-  async respond (): Promise<NativeResponse> {
-    return await this.options?.render?.()
-  }
-}

package/basic-react-native-declarative/adapter/declarations.ts

@@ -1,40 +0,0 @@
-import { RawResponseWrapper } from './RawResponseWrapper'
-import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
-import { AdapterContext, IAdapterEventBuilder, RawResponseOptions } from '@stone-js/core'
-import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
-
-/**
- * The platform identifier exposed on every incoming event's source.
- */
-export const NATIVE_PLATFORM = 'react-native'
-
-/**
- * The raw platform response. The native platform has no transport response:
- * the effect is a render, so the raw response is whatever the renderer returns.
- */
-export type NativeResponse = unknown
-
-/**
- * Raw response options carrying the deferred `render` effect, mirroring the
- * browser adapter's contract.
- */
-export interface RawNativeResponseOptions extends RawResponseOptions {
-  render?: () => NativeResponse | Promise<NativeResponse>
-}
-
-/**
- * The adapter context for the native proof-of-concept adapter.
- */
-export type NativeAdapterContext = AdapterContext<
-NativeNavigationEvent,
-NativeResponse,
-NativeEventSource,
-IncomingBrowserEvent,
-IncomingBrowserEventOptions,
-OutgoingBrowserResponse
->
-
-/**
- * The response builder used by the native adapter middleware.
- */
-export type NativeAdapterResponseBuilder = IAdapterEventBuilder<RawNativeResponseOptions, RawResponseWrapper>

package/basic-react-native-declarative/adapter/middleware.ts

@@ -1,73 +0,0 @@
-import { emitNativeRender } from './renderSink'
-import { NextMiddleware } from '@stone-js/core'
-import { CookieCollection } from '@stone-js/browser-core'
-import { NATIVE_PLATFORM, NativeAdapterContext, NativeAdapterResponseBuilder } from './declarations'
-
-/**
- * Transforms the raw navigation event into the intention: an
- * `IncomingBrowserEvent`, reused as-is from `@stone-js/browser-core`.
- *
- * This is the native mirror of the browser adapter's IncomingEventMiddleware:
- * `location` comes from the event's URL instead of `window.location`, and the
- * cookie collection is purely in memory (no `document`).
- */
-export class IncomingEventMiddleware {
-  /**
-   * Handle the incoming raw event.
-   *
-   * @param context - The adapter context.
-   * @param next - The next middleware.
-   * @returns The response builder.
-   */
-  async handle (
-    context: NativeAdapterContext,
-    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
-  ): Promise<NativeAdapterResponseBuilder> {
-    const url = new URL(context.rawEvent.url)
-
-    context
-      .incomingEventBuilder
-      .add('url', url)
-      .add('queryString', url.search)
-      .add('protocol', url.protocol.replace(':', ''))
-      .add('metadata', context.rawEvent.metadata ?? {})
-      .add('cookies', CookieCollection.create(undefined, {}))
-      .add('source', {
-        rawEvent: context.rawEvent,
-        platform: NATIVE_PLATFORM,
-        rawContext: context.executionContext
-      })
-
-    return await next(context)
-  }
-}
-
-/**
- * Contributes the deferred render effect: once the kernel has produced the
- * outgoing response, hand it to the registered render target.
- *
- * This is the native mirror of the role `BrowserResponseMiddleware` plays for
- * the browser platform in `@stone-js/use-react`.
- */
-export class ResponseMiddleware {
-  /**
-   * Handle the outgoing response.
-   *
-   * @param context - The adapter context.
-   * @param next - The next middleware.
-   * @returns The response builder.
-   */
-  async handle (
-    context: NativeAdapterContext,
-    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
-  ): Promise<NativeAdapterResponseBuilder> {
-    context.rawResponseBuilder.add('render', () => {
-      if (context.outgoingResponse !== undefined) {
-        emitNativeRender(context.outgoingResponse)
-      }
-      return context.outgoingResponse
-    })
-
-    return await next(context)
-  }
-}

package/basic-react-native-declarative/adapter/nativeAdapterBlueprint.ts

@@ -1,51 +0,0 @@
-import { NATIVE_PLATFORM } from './declarations'
-import { NativeAdapter } from './NativeAdapter'
-import { NativeErrorHandler } from './NativeErrorHandler'
-import { IncomingEventMiddleware, ResponseMiddleware } from './middleware'
-import { AdapterConfig, AppConfig, defaultKernelResolver, IBlueprint, StoneBlueprint } from '@stone-js/core'
-import { OutgoingBrowserResponse, OutgoingBrowserResponseOptions } from '@stone-js/browser-core'
-
-/**
- * Adapter resolver for the native proof-of-concept adapter.
- *
- * @param blueprint - The `IBlueprint` providing configuration and dependencies.
- * @returns A `NativeAdapter` instance.
- */
-export const nativeAdapterResolver = (blueprint: IBlueprint): NativeAdapter => {
-  return NativeAdapter.create(blueprint)
-}
-
-/**
- * Blueprint for the native proof-of-concept adapter.
- *
- * Activated the canonical way: handed to `@StoneApp(options, [blueprints])`
- * (declarative) or `defineStoneApp(handler, options, [blueprints])`
- * (imperative). Being the only adapter, it is selected automatically.
- */
-export const nativeAdapterBlueprint: StoneBlueprint = {
-  stone: {
-    kernel: {
-      responseResolver: (options: OutgoingBrowserResponseOptions) => {
-        return OutgoingBrowserResponse.create({ ...options, statusCode: options.statusCode ?? 200 })
-      }
-    },
-    adapters: [
-      {
-        current: false,
-        default: true,
-        variant: 'native',
-        platform: NATIVE_PLATFORM,
-        middleware: [
-          { module: IncomingEventMiddleware, isClass: true, priority: 0 },
-          { module: ResponseMiddleware, isClass: true, priority: 10 }
-        ],
-        resolver: nativeAdapterResolver,
-        eventHandlerResolver: defaultKernelResolver,
-        events: [],
-        errorHandlers: {
-          default: { module: NativeErrorHandler, isClass: true }
-        }
-      } as unknown as AdapterConfig
-    ]
-  } as Partial<AppConfig> as AppConfig
-}

package/basic-react-native-declarative/adapter/renderSink.ts

@@ -1,52 +0,0 @@
-import { OutgoingBrowserResponse } from '@stone-js/browser-core'
-
-/**
- * A render listener: receives the kernel's outgoing response for display.
- */
-export type NativeRenderListener = (response: OutgoingBrowserResponse) => void
-
-/**
- * An error listener: receives adapter-level errors for display.
- */
-export type NativeErrorListener = (error: Error) => void
-
-let renderListener: NativeRenderListener | undefined
-let errorListener: NativeErrorListener | undefined
-
-/**
- * Register the render effect target. In this proof of concept the target is
- * the React root component's state; the future `@stone-js/use-react-native`
- * response middleware will push into the native navigation stack instead.
- *
- * @param listener - The render listener.
- */
-export function onNativeRender (listener: NativeRenderListener): void {
-  renderListener = listener
-}
-
-/**
- * Register the error display target.
- *
- * @param listener - The error listener.
- */
-export function onNativeError (listener: NativeErrorListener): void {
-  errorListener = listener
-}
-
-/**
- * Push an outgoing response to the registered render target.
- *
- * @param response - The kernel's outgoing response.
- */
-export function emitNativeRender (response: OutgoingBrowserResponse): void {
-  renderListener?.(response)
-}
-
-/**
- * Push an error to the registered error target.
- *
- * @param error - The error to display.
- */
-export function emitNativeError (error: Error): void {
-  errorListener?.(error)
-}

package/basic-react-native-declarative/app/WelcomeController.ts

@@ -1,66 +0,0 @@
-import { Controller, Match } from '@stone-js/router'
-import { IncomingBrowserEvent } from '@stone-js/browser-core'
-
-/**
- * The payload every route of this starter returns.
- */
-export interface WelcomeData {
-  message: string
-  route: string
-  framework: {
-    name: string
-    tagline: string
-    docs: string
-  }
-}
-
-/**
- * WelcomeController
- *
- * The routes are matched against the URL carried by each navigation event,
- * exactly like they would be in a browser SPA or behind an HTTP adapter:
- * the domain does not know it is running inside a native application.
- */
-@Controller()
-export class WelcomeController {
-  /**
-   * The landing route, dispatched once when the application starts.
-   *
-   * @returns The welcome payload.
-   */
-  @Match('/')
-  welcome (): WelcomeData {
-    return this.present('Welcome to Stone.js on React Native!', '/')
-  }
-
-  /**
-   * A parameterized route: the `name` route parameter is read from the event.
-   *
-   * @param event - The incoming navigation event.
-   * @returns The greeting payload.
-   */
-  @Match('/hello/:name')
-  hello (event: IncomingBrowserEvent): WelcomeData {
-    const name = String(event.get<string>('name', 'World'))
-    return this.present(`Hello ${name}! Same domain, native screen.`, `/hello/${name}`)
-  }
-
-  /**
-   * Build the branded payload returned by every route.
-   *
-   * @param message - The message to display.
-   * @param route - The matched route path.
-   * @returns The payload.
-   */
-  private present (message: string, route: string): WelcomeData {
-    return {
-      message,
-      route,
-      framework: {
-        name: 'Stone.js',
-        tagline: 'The continuum framework',
-        docs: 'https://stonejs.dev'
-      }
-    }
-  }
-}