polen 0.11.0-next.14 → 0.11.0-next.15

package/src/lib/react-router-effect/types.ts

@@ -0,0 +1,82 @@
+import type { Http } from '@wollybeard/kit'
+import type { Effect, Schema } from 'effect'
+import type React from 'react'
+import type { RouteObject } from 'react-router'
+
+/**
+ * Base route handle interface that can be extended by routes.
+ * Includes properties like custom status codes.
+ */
+export interface RouteHandle {
+  /**
+   * Optional HTTP status code to use for this route.
+   */
+  statusCode?: Http.Status.Code.All
+}
+
+/**
+ * Global registry of route schemas that can be augmented by route definitions.
+ * This enables type-safe access to route data by ID.
+ */
+export interface RouteSchemaRegistry {
+  // Routes will augment this interface
+}
+
+/**
+ * Get the schema type from the registry for a given route ID.
+ */
+export type GetRouteSchema<TRouteId extends keyof RouteSchemaRegistry> = RouteSchemaRegistry[TRouteId]
+
+/**
+ * Handle interface for routes with Effect schemas attached.
+ * Extends the base RouteHandle to include schema information.
+ */
+export interface SchemaRouteHandle<TSchema extends Schema.Schema.Any = Schema.Schema.Any> extends RouteHandle {
+  /**
+   * The Effect schema for this route's loader data.
+   */
+  schema: TSchema
+  /**
+   * Optional schema ID for registry lookups.
+   */
+  schemaId?: string | undefined
+}
+
+/**
+ * Route object with an attached Effect schema.
+ */
+export type SchemaRoute<TSchema extends Schema.Schema.Any = Schema.Schema.Any> = RouteObject & {
+  handle: SchemaRouteHandle<TSchema>
+  loader?: RouteObject['loader']
+}
+
+/**
+ * Configuration for creating a schema-aware route.
+ */
+export interface SchemaRouteConfig<TSchema extends Schema.Schema.Any> {
+  /**
+   * The Effect schema for validating and encoding/decoding loader data.
+   */
+  schema: TSchema
+  /**
+   * The loader function that returns data matching the schema type.
+   * Can return either a Promise or an Effect.
+   * The returned data will be automatically encoded using the schema.
+   */
+  loader?:
+    | ((args: any) => Promise<Schema.Schema.Type<TSchema>>)
+    | ((args: any) => Effect.Effect<Schema.Schema.Type<TSchema>, any, any>)
+  /**
+   * Additional handle properties beyond the schema.
+   */
+  handle?: Omit<SchemaRouteHandle<TSchema>, 'schema'>
+
+  // Route properties
+  id?: string
+  path?: string
+  index?: boolean
+  children?: RouteObject[]
+  Component?: React.ComponentType<any>
+  element?: React.ReactNode
+  errorElement?: React.ReactNode
+}

package/src/lib/react-router-effect/use-loader-data.ts

@@ -0,0 +1,133 @@
+import { Schema } from 'effect'
+import { useLoaderData as useLoaderDataRR, useMatches } from 'react-router'
+import type { GetRouteSchema, RouteSchemaRegistry } from './types.js'
+
+/**
+ * Hook that retrieves and automatically decodes loader data based on a provided Effect schema.
+ * This can access data from any route in the hierarchy that has the matching schema.
+ *
+ * @example
+ * ```typescript
+ * function CatalogView() {
+ *   // Get current route's catalog data
+ *   const catalog = useLoaderData(CatalogSchema)
+ *
+ *   // Get ancestor route's user data
+ *   const user = useLoaderData(UserSchema)
+ *
+ *   return <div>{user.name}'s {catalog.name}</div>
+ * }
+ * ```
+ */
+export function useLoaderData<TSchema extends Schema.Schema.Any>(
+  schema: TSchema,
+): Schema.Schema.Type<TSchema> {
+  const matches = useMatches()
+
+  // Find the match that has this exact schema attached
+  const match = matches.find(m => (m.handle as any)?.schema === schema)
+
+  if (!match) {
+    throw new Error(
+      `No route found with the specified schema. Make sure the route uses schemaRoute() or has the schema in its handle.`,
+    )
+  }
+
+  if (match.data === undefined) {
+    throw new Error(
+      `No loader data found for route ${match.id}. Make sure the route has a loader.`,
+    )
+  }
+
+  // Decode the data using the schema
+  return Schema.decodeUnknownSync(schema as any)(match.data) as Schema.Schema.Type<TSchema>
+}
+
+/**
+ * Hook that retrieves loader data by route ID with type safety from the RouteSchemaRegistry.
+ * Routes must augment the registry interface for this to work.
+ *
+ * @example
+ * ```typescript
+ * // In route file:
+ * declare module '#lib/react-router-effect/types' {
+ *   interface RouteSchemaRegistry {
+ *     'catalog': typeof CatalogSchema
+ *   }
+ * }
+ *
+ * // In component:
+ * const catalog = useRouteDataById('catalog') // Type-safe!
+ * ```
+ */
+export function useRouteDataById<TRouteId extends keyof RouteSchemaRegistry>(
+  routeId: TRouteId,
+): Schema.Schema.Type<GetRouteSchema<TRouteId>> {
+  const matches = useMatches()
+  const match = matches.find(m => m.id === routeId)
+
+  if (!match) {
+    throw new Error(`No route found with ID "${String(routeId)}"`)
+  }
+
+  if (!(match.handle as any)?.schema) {
+    throw new Error(
+      `Route "${String(routeId)}" does not have a schema attached. Use schemaRoute() to create the route.`,
+    )
+  }
+
+  if (match.data === undefined) {
+    throw new Error(
+      `No loader data found for route "${String(routeId)}". Make sure the route has a loader.`,
+    )
+  }
+
+  return Schema.decodeUnknownSync((match.handle as any).schema)(match.data) as any
+}
+
+/**
+ * Hook that returns all route data from the current route hierarchy, decoded using their schemas.
+ * Returns an object keyed by route ID.
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const routeData = useRouteData()
+ *   // Access any route's data by ID
+ *   const user = routeData.user
+ *   const catalog = routeData.catalog
+ * }
+ * ```
+ */
+export function useRouteData(): Record<string, unknown> {
+  const matches = useMatches()
+
+  return matches.reduce((acc, match) => {
+    // Only process matches that have both a schema and data
+    if ((match.handle as any)?.schema && match.data !== undefined && match.id) {
+      try {
+        const decoded = Schema.decodeUnknownSync((match.handle as any).schema as any)(match.data)
+        acc[match.id] = decoded
+      } catch (error) {
+        // Log decode errors but don't throw to allow partial data access
+      }
+    }
+    return acc
+  }, {} as Record<string, unknown>)
+}
+
+/**
+ * Original useLoaderData behavior - returns loader data for current route without schema decoding.
+ * Provided for backward compatibility.
+ */
+export function useLoaderDataRaw<T = unknown>(routeId?: string): T {
+  const loaderData = routeId
+    ? (useLoaderDataRR as any)(routeId)
+    : useLoaderDataRR()
+
+  if (loaderData === undefined) {
+    throw new Error(`No loader data returned from route ${routeId ?? '<current>'}`)
+  }
+
+  return loaderData as T
+}

package/src/lib/revision/$.ts

@@ -0,0 +1 @@
+export * as Revision from './revision.js'

package/src/lib/revision/revision.ts

@@ -0,0 +1,64 @@
+import { Change } from '#lib/change/$'
+import { DateOnly } from '#lib/date-only/$'
+import { S } from '#lib/kit-temp/effect'
+import { Order } from 'effect'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const Revision = S.TaggedStruct('Revision', {
+  date: DateOnly.DateOnly,
+  changes: S.Array(Change.Change),
+}).annotations({
+  identifier: 'Revision',
+  title: 'Revision',
+  description: 'A revision in the schema history',
+})
+
+export type Revision = S.Schema.Type<typeof Revision>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+/**
+ * Create a Revision instance with validation
+ */
+export const make = Revision.make
+
+// ============================================================================
+// Type Guard
+// ============================================================================
+
+export const is = S.is(Revision)
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+export const order: Order.Order<Revision> = Order.reverse(Order.mapInput(DateOnly.order, (revision) => revision.date))
+
+export const min = Order.min(order)
+
+export const max = Order.max(order)
+
+export const lessThan = Order.lessThan(order)
+
+export const greaterThan = Order.greaterThan(order)
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Revision)
+
+export const decodeSync = S.decodeSync(Revision)
+
+export const encode = S.encode(Revision)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Revision)

package/src/lib/schema/$.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'vitest'
+import * as SchemaDefinition from '../schema-definition/schema-definition.js'
+import { Version } from '../version/$.js'
+import { Schema } from './$.js'
+
+describe('Schema', () => {
+  const mockGraphQLSchema = SchemaDefinition.sdl.decode(`
+    type Query {
+      hello: String
+    }
+  `)
+
+  test('creates versioned schema', () => {
+    const versionedSchema = Schema.Versioned.make({
+      version: Version.decodeSync('1.0.0'),
+      branchPoint: null,
+      revisions: [],
+      definition: mockGraphQLSchema as any,
+    })
+
+    expect(versionedSchema._tag).toBe('SchemaVersioned')
+    expect(Version.toString(versionedSchema.version)).toBe('1.0.0')
+  })
+
+  test('creates unversioned schema', () => {
+    const unversionedSchema = Schema.Unversioned.make({
+      revisions: [],
+      definition: mockGraphQLSchema as any,
+    })
+
+    expect(unversionedSchema._tag).toBe('SchemaUnversioned')
+  })
+
+  test('type guards work correctly for union', () => {
+    const versionedSchema = Schema.Versioned.make({
+      version: Version.decodeSync('1.0.0'),
+      branchPoint: null,
+      revisions: [],
+      definition: mockGraphQLSchema as any,
+    })
+
+    const unversionedSchema = Schema.Unversioned.make({
+      revisions: [],
+      definition: mockGraphQLSchema as any,
+    })
+
+    expect(Schema.is(versionedSchema)).toBe(true)
+    expect(Schema.is(unversionedSchema)).toBe(true)
+    expect(Schema.Versioned.is(versionedSchema)).toBe(true)
+    expect(Schema.Versioned.is(unversionedSchema)).toBe(false)
+    expect(Schema.Unversioned.is(versionedSchema)).toBe(false)
+    expect(Schema.Unversioned.is(unversionedSchema)).toBe(true)
+  })
+})

package/src/lib/schema/schema.ts

@@ -0,0 +1,50 @@
+import { S } from '#lib/kit-temp/effect'
+import { Match } from 'effect'
+import * as Unversioned from './unversioned.js'
+import * as Versioned from './versioned.js'
+
+// ============================================================================
+// Members
+// ============================================================================
+
+export * as Unversioned from './unversioned.js'
+export * as Versioned from './versioned.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const Schema = S.Union(Versioned.Versioned, Unversioned.Unversioned)
+
+export type Schema = S.Schema.Type<typeof Schema>
+
+// ============================================================================
+// Type Guard
+// ============================================================================
+
+export const is = S.is(Schema)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(Schema)
+export const encode = S.encode(Schema)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Schema)
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+export const getVersion = (schema: Schema) =>
+  Match.value(schema).pipe(
+    Match.tagsExhaustive({
+      SchemaUnversioned: () => undefined,
+      SchemaVersioned: (s) => s.version,
+    }),
+  )

package/src/lib/schema/unversioned.ts

@@ -0,0 +1,59 @@
+import { S } from '#lib/kit-temp/effect'
+import { Order } from 'effect'
+import { Revision } from '../revision/$.js'
+import { SchemaDefinition } from '../schema-definition/$.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const Unversioned = S.TaggedStruct('SchemaUnversioned', {
+  revisions: S.Array(Revision.Revision),
+  definition: SchemaDefinition.SchemaDefinition,
+}).annotations({
+  identifier: 'SchemaUnversioned',
+  title: 'Unversioned Schema',
+  description: 'A GraphQL schema without semantic versioning',
+  adt: { name: 'Schema' },
+})
+
+export type Unversioned = S.Schema.Type<typeof Unversioned>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Unversioned.make
+
+// ============================================================================
+// Type Guard
+// ============================================================================
+
+export const is = S.is(Unversioned)
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+/**
+ * Orders by first revision date if any
+ */
+export const order: Order.Order<Unversioned> = Order.mapInput(Order.string, (schema) => schema.revisions[0]?.date ?? '')
+
+export const min = Order.min(order)
+export const max = Order.max(order)
+export const lessThan = Order.lessThan(order)
+export const greaterThan = Order.greaterThan(order)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(Unversioned)
+export const encode = S.encode(Unversioned)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Unversioned)

package/src/lib/schema/versioned.ts

@@ -0,0 +1,83 @@
+import { S } from '#lib/kit-temp/effect'
+import type { ObjReplace } from '#lib/kit-temp/other'
+import { Order } from 'effect'
+import { Revision } from '../revision/$.js'
+import { SchemaDefinition } from '../schema-definition/$.js'
+import { Version } from '../version/$.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export interface BranchPoint {
+  readonly schema: Versioned
+  readonly revision: Revision.Revision
+}
+
+export interface BranchPointEncoded {
+  readonly schema: VersionedEncoded
+  readonly revision: Revision.Revision
+}
+
+export interface Versioned {
+  readonly _tag: 'SchemaVersioned'
+  readonly version: Version.Version
+  readonly branchPoint: BranchPoint | null
+  readonly revisions: ReadonlyArray<Revision.Revision>
+  readonly definition: SchemaDefinition.SchemaDefinition
+}
+
+export interface VersionedEncoded extends
+  ObjReplace<Versioned, {
+    readonly version: S.Schema.Encoded<typeof Version.Version>
+    readonly branchPoint: BranchPointEncoded | null
+    readonly revisions: ReadonlyArray<S.Schema.Encoded<typeof Revision.Revision>>
+    readonly definition: S.Schema.Encoded<typeof SchemaDefinition.SchemaDefinition>
+  }>
+{}
+
+export const Versioned = S.TaggedStruct('SchemaVersioned', {
+  version: Version.Version,
+  branchPoint: S.NullOr(S.Struct({
+    schema: S.suspend((): S.Schema<Versioned, VersionedEncoded> => Versioned as any),
+    revision: Revision.Revision,
+  })),
+  revisions: S.Array(Revision.Revision),
+  definition: SchemaDefinition.SchemaDefinition,
+})
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Versioned.make
+
+// ============================================================================
+// Type Guard
+// ============================================================================
+
+export const is = S.is(Versioned)
+
+// ============================================================================
+// Ordering
+// ============================================================================
+
+export const order: Order.Order<Versioned> = Order.mapInput(Version.order, (schema) => schema.version)
+
+export const min = Order.min(order)
+export const max = Order.max(order)
+export const lessThan = Order.lessThan(order)
+export const greaterThan = Order.greaterThan(order)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(Versioned)
+export const encode = S.encode(Versioned)
+
+// ============================================================================
+// Equivalence
+// ============================================================================
+
+export const equivalence = S.equivalence(Versioned)

package/src/lib/schema-definition/$.test.ts

@@ -0,0 +1,58 @@
+import { expect } from 'vitest'
+import { Test } from '../../../tests/unit/helpers/test.js'
+import * as SchemaDefinition from './schema-definition.js'
+
+interface SchemaTestCase {
+  sdl: string
+  operation: 'decode' | 'isEmpty'
+  expected: boolean | string
+}
+
+const sdl1 = `
+  type Query {
+    hello: String
+    world: String
+  }
+`
+
+const sdl2 = `
+  type Query {
+    world: String
+    hello: String
+  }
+`
+
+// dprint-ignore
+Test.suite<SchemaTestCase>('SchemaDefinition', [
+  { name: 'sdl.decode creates schema from SDL string',  sdl: sdl1,          operation: 'decode',  expected: 'type Query' },
+  { name: 'isEmpty detects empty schemas',              sdl: `type Query`,  operation: 'isEmpty', expected: true },
+  { name: 'isEmpty returns false for non-empty',        sdl: sdl1,          operation: 'isEmpty', expected: false },
+], ({ sdl, operation, expected }) => {
+  const schema = SchemaDefinition.sdl.decode(sdl)
+  
+  switch (operation) {
+    case 'decode':
+      expect(SchemaDefinition.is(schema)).toBe(true)
+      expect(SchemaDefinition.sdl.encode(schema)).toContain(expected as string)
+      break
+    case 'isEmpty':
+      expect(SchemaDefinition.isEmpty(schema as any)).toBe(expected)
+      break
+  }
+})
+
+interface EquivalenceTestCase {
+  sdl1: string
+  sdl2: string
+  shouldBeEqual: boolean
+}
+
+// dprint-ignore
+Test.suite<EquivalenceTestCase>('equivalence', [
+  { name: 'different field order means different SDL',  sdl1: sdl1, sdl2: sdl2, shouldBeEqual: false },
+  { name: 'same SDL produces equivalent schemas',       sdl1: sdl1, sdl2: sdl1, shouldBeEqual: true },
+], ({ sdl1, sdl2, shouldBeEqual }) => {
+  const schema1 = SchemaDefinition.sdl.decode(sdl1)
+  const schema2 = SchemaDefinition.sdl.decode(sdl2)
+  expect(SchemaDefinition.equivalence(schema1 as any, schema2 as any)).toBe(shouldBeEqual)
+})

package/src/lib/schema-definition/$.ts

@@ -0,0 +1 @@
+export * as SchemaDefinition from './schema-definition.js'

package/src/lib/schema-definition/graphql-ast.ts

@@ -0,0 +1,14 @@
+import { S } from '#lib/kit-temp/effect'
+import { type DocumentNode } from 'graphql'
+
+const GraphQLIsDocumentNode = (input: unknown): input is DocumentNode =>
+  typeof input === 'object'
+  && input !== null
+  && 'kind' in input
+  && (input as any).kind === 'Document'
+
+export const graphqlAst = S.declare(GraphQLIsDocumentNode, {
+  identifier: 'GraphQLDocumentNode',
+  title: 'GraphQL AST',
+  description: 'GraphQL Abstract Syntax Tree',
+})