polen 0.11.0-next.17 → 0.11.0-next.18

package/src/template/components/GraphQLInteractive/lib/parser.ts

@@ -7,6 +7,7 @@
 
 import { Api } from '#api/iso'
 import type { CodeAnnotation } from 'codehike/code'
+import { Either } from 'effect'
 import {
   getNamedType,
   type GraphQLArgument,
@@ -504,41 +505,65 @@ class SemanticContext {
 }
 
 /**
- * Parse GraphQL code into interactive tokens with semantic information
+ * Error types for GraphQL parsing
+ */
+export type ParseError =
+  | { readonly _tag: 'InvalidInput'; readonly message: string }
+  | { readonly _tag: 'DocumentTooLarge'; readonly maxSize: number; readonly actualSize: number }
+  | { readonly _tag: 'TreeSitterError'; readonly message: string }
+  | { readonly _tag: 'ParserInitError'; readonly message: string }
+
+const makeParseError = {
+  invalidInput: (message: string): ParseError => ({ _tag: 'InvalidInput', message }),
+  documentTooLarge: (maxSize: number, actualSize: number): ParseError => ({
+    _tag: 'DocumentTooLarge',
+    maxSize,
+    actualSize,
+  }),
+  treeSitterError: (message: string): ParseError => ({ _tag: 'TreeSitterError', message }),
+  parserInitError: (message: string): ParseError => ({ _tag: 'ParserInitError', message }),
+}
+
+/**
+ * Parse GraphQL code into interactive tokens with semantic information (Either version)
  *
  * @param code - The raw GraphQL code to parse
  * @param annotations - CodeHike annotations that might affect rendering
  * @param schema - Optional GraphQL schema for semantic analysis
- * @returns Array of tokens representing the parsed code
+ * @returns Either with array of tokens on right or ParseError on left
  */
-export async function parseGraphQLWithTreeSitter(
+export async function parseGraphQLWithTreeSitterEither(
   code: string,
   annotations: CodeAnnotation[] = [],
   schema?: GraphQLSchema,
-): Promise<GraphQLToken[]> {
+): Promise<Either.Either<GraphQLToken[], ParseError>> {
   // Validate input
   if (!code || typeof code !== 'string') {
-    throw new Error('Invalid GraphQL code: code must be a non-empty string')
+    return Either.left(makeParseError.invalidInput('Invalid GraphQL code: code must be a non-empty string'))
   }
 
   // Prevent parsing extremely large documents that could cause performance issues
-  if (code.length > 100_000) {
-    throw new Error('GraphQL document too large: maximum 100,000 characters allowed')
+  const maxSize = 100_000
+  if (code.length > maxSize) {
+    return Either.left(makeParseError.documentTooLarge(maxSize, code.length))
   }
 
   // Step 1: Parse with tree-sitter
-  const parser = await getParser()
+  let parser: WebTreeSitter.Parser
+  try {
+    parser = await getParser()
+  } catch (error) {
+    return Either.left(makeParseError.parserInitError(
+      error instanceof Error ? error.message : 'Failed to initialize parser',
+    ))
+  }
+
   const tree = parser.parse(code)
 
   if (!tree) {
-    throw new Error('Tree-sitter failed to parse GraphQL code')
+    return Either.left(makeParseError.treeSitterError('Tree-sitter failed to parse GraphQL code'))
   }
 
-  // Check if tree-sitter found syntax errors (disabled for now as it may be too strict)
-  // if (tree.rootNode.hasError) {
-  //   throw new Error('GraphQL syntax error detected by tree-sitter parser')
-  // }
-
   try {
     // Step 2: Walk tree and attach semantics
     const tokens = collectTokensWithSemantics(tree, code, schema, annotations)
@@ -546,26 +571,53 @@ export async function parseGraphQLWithTreeSitter(
     // Step 3: Add error hint tokens after invalid fields
     const tokensWithHints = addErrorHintTokens(tokens, code, annotations)
 
-    return tokensWithHints
+    return Either.right(tokensWithHints)
+  } catch (error) {
+    return Either.left(makeParseError.treeSitterError(
+      error instanceof Error ? error.message : 'Failed to process tokens',
+    ))
   } finally {
-    // ## Tree-sitter Resource Lifecycle Management
-    //
-    // Tree-sitter creates native WASM objects that must be explicitly freed to prevent memory leaks.
-    // The tree object holds references to parsed nodes and internal parser state that won't be
-    // garbage collected automatically by JavaScript.
-    //
-    // Critical cleanup points:
-    // 1. Always call tree.delete() in a finally block to ensure cleanup even on errors
-    // 2. Do not access tree or any of its nodes after calling delete()
-    // 3. The parser instance is cached globally and reused across multiple parsing calls
-    //
-    // Memory safety: Once tree.delete() is called, all WebTreeSitter.Node references become invalid.
-    // Our tokens hold references to these nodes, but only use their text and position properties
-    // which are copied during token creation, so the nodes can be safely deleted.
+    // Tree-sitter Resource Lifecycle Management
     tree.delete()
   }
 }
 
+/**
+ * Parse GraphQL code into interactive tokens with semantic information
+ *
+ * @param code - The raw GraphQL code to parse
+ * @param annotations - CodeHike annotations that might affect rendering
+ * @param schema - Optional GraphQL schema for semantic analysis
+ * @returns Array of tokens representing the parsed code
+ * @deprecated Use parseGraphQLWithTreeSitterEither for better error handling
+ */
+export async function parseGraphQLWithTreeSitter(
+  code: string,
+  annotations: CodeAnnotation[] = [],
+  schema?: GraphQLSchema,
+): Promise<GraphQLToken[]> {
+  const result = await parseGraphQLWithTreeSitterEither(code, annotations, schema)
+
+  if (Either.isLeft(result)) {
+    const error = result.left
+    switch (error._tag) {
+      case 'InvalidInput':
+        throw new Error(error.message)
+      case 'DocumentTooLarge':
+        throw new Error(`GraphQL document too large: maximum ${error.maxSize} characters allowed`)
+      case 'TreeSitterError':
+      case 'ParserInitError':
+        throw new Error(error.message)
+      default: {
+        const exhaustiveCheck: never = error
+        throw new Error(`Unhandled parse error: ${JSON.stringify(exhaustiveCheck)}`)
+      }
+    }
+  }
+
+  return result.right
+}
+
 /**
  * Get or create the tree-sitter parser instance
  */

package/src/template/components/VersionCoveragePicker.tsx

@@ -1,6 +1,6 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { VersionCoverage } from '#lib/version-selection/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Select } from '@radix-ui/themes'
 import { HashMap } from 'effect'
 import type { FC } from 'react'
@@ -30,12 +30,11 @@ export const VersionCoveragePicker: FC<Props> = ({
     <Select.Root
       value={VersionCoverage.toLabel(current)}
       onValueChange={(label) => {
-        // Find selection by label and pick first version from it
+        // Find the full version coverage by label and pass it entirely
         const selection = options.find(s => VersionCoverage.toLabel(s) === label)
         if (selection) {
-          const versions = VersionCoverage.toVersions(selection)
-          const version = versions[0]
-          if (version) onChange(version)
+          // Pass the entire VersionCoverage, not just the first version
+          onChange(selection)
         }
       }}
     >

package/src/template/components/home/QuickStart.tsx

@@ -1,5 +1,6 @@
 import { Box, Card, Heading, Section, Tabs, Text } from '@radix-ui/themes'
 import { highlight } from 'codehike/code'
+import { Effect } from 'effect'
 import * as React from 'react'
 import { CodeBlock } from '../CodeBlock.js'
 
@@ -73,14 +74,22 @@ export const QuickStartSection: React.FC<Props> = ({ examples = defaultExamples
 
   React.useEffect(() => {
     const highlightExamples = async () => {
-      const highlighted = await Promise.all(
-        examples.map(async (example) => ({
-          label: example.label,
-          codeblock: await highlight(
-            { value: example.code, lang: example.language, meta: '' },
-            { theme: 'github-light' },
+      const highlighted = await Effect.runPromise(
+        Effect.all(
+          examples.map((example) =>
+            Effect.tryPromise({
+              try: async () => ({
+                label: example.label,
+                codeblock: await highlight(
+                  { value: example.code, lang: example.language, meta: '' },
+                  { theme: 'github-light' },
+                ),
+              }),
+              catch: (error) => new Error(`Failed to highlight ${example.label}: ${error}`),
+            })
           ),
-        })),
+          { concurrency: 'unbounded' },
+        ),
       )
       setHighlightedExamples(highlighted)
     }

package/src/template/hooks/use-highlighted.ts

@@ -1,5 +1,6 @@
 import type { HighlightedCode } from 'codehike/code'
 import { highlight } from 'codehike/code'
+import { Duration, Effect } from 'effect'
 import * as React from 'react'
 
 /**
@@ -29,26 +30,37 @@ export const useHighlighted = (
   const [highlightedCode, setHighlightedCode] = React.useState<HighlightedCode | null>(null)
 
   React.useEffect(() => {
-    const highlightContent = async () => {
-      // Add a timeout to detect if highlight is hanging
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error('Highlight timeout after 5 seconds')), 5000)
-      })
-
-      const highlightPromise = highlight(
-        {
-          value: content,
-          lang: config.lang,
-          meta: metaString,
-        },
-        {
-          theme: 'github-light',
-        },
-      )
+    const HIGHLIGHT_TIMEOUT = Duration.seconds(5)
 
-      const highlighted = await Promise.race([highlightPromise, timeoutPromise])
-
-      setHighlightedCode(highlighted as any)
+    const highlightContent = async () => {
+      try {
+        const highlighted = await Effect.runPromise(
+          Effect.tryPromise({
+            try: () =>
+              highlight(
+                {
+                  value: content,
+                  lang: config.lang,
+                  meta: metaString,
+                },
+                {
+                  theme: 'github-light',
+                },
+              ),
+            catch: (error) => new Error(`Highlight failed: ${error}`),
+          }).pipe(
+            Effect.timeout(HIGHLIGHT_TIMEOUT),
+            Effect.catchTag(
+              'TimeoutException',
+              () => Effect.fail(new Error(`Highlight timeout after ${Duration.toSeconds(HIGHLIGHT_TIMEOUT)} seconds`)),
+            ),
+          ),
+        )
+        setHighlightedCode(highlighted)
+      } catch (error) {
+        console.error('Failed to highlight code:', error)
+        setHighlightedCode(null)
+      }
     }
     highlightContent()
   }, [content, config.lang, config.interactive])

package/src/template/lib/fetch-text.ts

@@ -1,13 +1,54 @@
+import { Either } from 'effect'
+
+/**
+ * Error type for fetch failures
+ */
+export interface FetchError {
+  readonly _tag: 'FetchError'
+  readonly url: string
+  readonly status: number
+  readonly statusText: string
+  readonly message: string
+}
+
+const makeFetchError = (url: string, status: number, statusText: string): FetchError => ({
+  _tag: 'FetchError',
+  url,
+  status,
+  statusText,
+  message: `Failed to fetch: ${url} (${status} ${statusText})`,
+})
+
 /**
  * Fetch text content from a URL
  * @param url - The URL to fetch from
+ * @returns Either with text content on right or FetchError on left
+ */
+export const fetchTextEither = async (url: string): Promise<Either.Either<string, FetchError>> => {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      return Either.left(makeFetchError(url, response.status, response.statusText))
+    }
+    const text = await response.text()
+    return Either.right(text)
+  } catch (error) {
+    // Network errors or other exceptions
+    return Either.left(makeFetchError(url, 0, 'Network Error'))
+  }
+}
+
+/**
+ * Fetch text content from a URL (legacy throwing version)
+ * @param url - The URL to fetch from
  * @returns Promise that resolves to the text content
  * @throws Error if the request fails
+ * @deprecated Use fetchTextEither for better error handling
  */
 export const fetchText = async (url: string): Promise<string> => {
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch: ${url} (${response.status} ${response.statusText})`)
+  const result = await fetchTextEither(url)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.message)
   }
-  return response.text()
+  return result.right
 }

package/src/template/routes/examples/name.tsx

@@ -4,6 +4,7 @@ import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
 import { Version } from '#lib/version/$'
 import { Heading } from '@radix-ui/themes'
 import { Str } from '@wollybeard/kit'
+import { Array, Option } from 'effect'
 import { useSearchParams } from 'react-router'
 import { examplesCatalog } from 'virtual:polen/project/examples'
 import { schemasCatalog } from 'virtual:polen/project/schemas'
@@ -23,10 +24,11 @@ export const nameLoader = async ({ params }: any) => {
   }
 
   // Check if the example exists
-  const example = examplesCatalog.examples.find((e: any) => e.name === name)
-  if (!example) {
+  const exampleOption = Array.findFirst(examplesCatalog.examples, (e) => e.name === name)
+  if (Option.isNone(exampleOption)) {
     throw new Response('Not Found', { status: 404 })
   }
+  const example = exampleOption.value
 
   return example
 }

package/src/template/stores/toast.ts

@@ -1,4 +1,4 @@
-import { Schema as S } from 'effect'
+import { Duration, Schema as S } from 'effect'
 import { proxy } from 'valtio'
 
 // ============================================================================
@@ -68,8 +68,10 @@ export const initialState: State = {
   toasts: [],
 }
 
+const DEFAULT_TOAST_DURATION = Duration.seconds(5)
+
 const toastDefaults = {
-  duration: 5000,
+  duration: Duration.toMillis(DEFAULT_TOAST_DURATION),
   actions: [],
 } satisfies Partial<Toast>
 
@@ -96,7 +98,8 @@ export const store = proxy({
 
     // Auto-remove after duration (default 5 seconds). Set duration to 0 to disable auto-dismiss
     if (toast.duration !== 0) {
-      setTimeout(() => store.remove(id), toast.duration || toastDefaults.duration)
+      const durationMs = toast.duration || toastDefaults.duration
+      setTimeout(() => store.remove(id), durationMs)
     }
 
     return id

package/build/lib/graph/$$.d.ts

@@ -1,2 +0,0 @@
-export * from './graph.js';
-//# sourceMappingURL=$$.d.ts.map

package/build/lib/graph/$$.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"$$.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/$$.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/lib/graph/$$.js

@@ -1,2 +0,0 @@
-export * from './graph.js';
-//# sourceMappingURL=$$.js.map

package/build/lib/graph/$$.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"$$.js","sourceRoot":"","sources":["../../../src/lib/graph/$$.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA"}

package/build/lib/graph/$.d.ts

@@ -1,2 +0,0 @@
-export * as Graph from './$$.js';
-//# sourceMappingURL=$.d.ts.map

package/build/lib/graph/$.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"$.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/$.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA"}

package/build/lib/graph/$.js

@@ -1,2 +0,0 @@
-export * as Graph from './$$.js';
-//# sourceMappingURL=$.js.map

package/build/lib/graph/$.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"$.js","sourceRoot":"","sources":["../../../src/lib/graph/$.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAA"}

package/build/lib/graph/graph.d.ts

@@ -1,127 +0,0 @@
-import { S } from '#lib/kit-temp/effect';
-/**
- * Dependency graph for tracking relationships between nodes
- * Used to efficiently handle dependencies in various contexts
- */
-export declare const DependencyGraph: S.Struct<{
-    /**
-     * Map from parent ID to array of child IDs (parent depends on children)
-     */
-    dependencies: S.Record$<typeof S.String, S.Array$<typeof S.String>>;
-    /**
-     * Map from child ID to array of parent IDs (child is depended on by parents)
-     */
-    dependents: S.Record$<typeof S.String, S.Array$<typeof S.String>>;
-}>;
-export type DependencyGraph = typeof DependencyGraph.Type;
-export declare const make: (props: {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, options?: S.MakeOptions) => {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-};
-/**
- * Create an empty dependency graph
- */
-export declare const create: () => DependencyGraph;
-/**
- * Add a dependency relationship (immutable)
- * @param graph - The dependency graph
- * @param parent - The parent node ID
- * @param child - The child node ID that the parent depends on
- * @returns A new graph with the dependency added
- */
-export declare const addDependency: (graph: DependencyGraph, parent: string, child: string) => DependencyGraph;
-/**
- * Add a dependency relationship (mutable)
- * @param graph - The dependency graph to mutate
- * @param parent - The parent node ID
- * @param child - The child node ID that the parent depends on
- */
-export declare const addDependencyMutable: (graph: DependencyGraph, parent: string, child: string) => void;
-/**
- * Find all nodes that have no dependencies (leaf nodes)
- */
-export declare const findLeafNodes: (graph: DependencyGraph) => Set<string>;
-/**
- * Check if all dependencies of a node have been processed
- */
-export declare const areDependenciesReady: (node: string, graph: DependencyGraph, processed: Set<string>) => boolean;
-/**
- * Get topological ordering of nodes (children before parents)
- * This ensures we process dependencies before the nodes that depend on them
- *
- * @param graph - The dependency graph
- * @returns Array of node IDs in topological order
- */
-export declare const topologicalSort: (graph: DependencyGraph) => string[];
-export declare const decode: (i: {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, overrideOptions?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<{
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, import("effect/ParseResult").ParseError, never>;
-export declare const decodeSync: (i: {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-};
-export declare const encode: (a: {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, overrideOptions?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<{
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, import("effect/ParseResult").ParseError, never>;
-export declare const encodeSync: (a: {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-}, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
-    readonly dependencies: {
-        readonly [x: string]: readonly string[];
-    };
-    readonly dependents: {
-        readonly [x: string]: readonly string[];
-    };
-};
-//# sourceMappingURL=graph.d.ts.map

package/build/lib/graph/graph.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,sBAAsB,CAAA;AAIxC;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B;;OAEG;;IAGH;;OAEG;;EAKH,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAIzD,eAAO,MAAM,IAAI;;;;;;;;;;;;;;CAAuB,CAAA;AAExC;;GAEG;AACH,eAAO,MAAM,MAAM,QAAO,eAItB,CAAA;AAIJ;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,eAAe,EACtB,QAAQ,MAAM,EACd,OAAO,MAAM,KACZ,eAqBF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,eAAe,EACtB,QAAQ,MAAM,EACd,OAAO,MAAM,KACZ,IAsBF,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,eAAe,KAAG,GAAG,CAAC,MAAM,CAYhE,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,OAAO,eAAe,EACtB,WAAW,GAAG,CAAC,MAAM,CAAC,KACrB,OAKF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,eAAe,KAAG,MAAM,EA2C9D,CAAA;AAID,eAAO,MAAM,MAAM;;;;;;;;;;;;;;kDAA4B,CAAA;AAC/C,eAAO,MAAM,UAAU;;;;;;;;;;;;;;CAAgC,CAAA;AACvD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;kDAA4B,CAAA;AAC/C,eAAO,MAAM,UAAU;;;;;;;;;;;;;;CAAgC,CAAA"}