polen 0.11.0-next.12 → 0.11.0-next.14

package/src/api/vite/plugins/schema-assets.ts

@@ -3,13 +3,13 @@ import { SchemaAugmentation } from '#api/schema-augmentation/index'
 import { createSchemaSource } from '#api/schema-source/index'
 import { Schema } from '#api/schema/index'
 import type { Vite } from '#dep/vite/index'
-import { Grafaid } from '#lib/grafaid/index'
-import { ViteVirtual } from '#lib/vite-virtual/index'
+import { GraphqlChangeset } from '#lib/graphql-changeset'
+import { SchemaLifecycle } from '#lib/schema-lifecycle'
+import { ViteVirtual } from '#lib/vite-virtual'
 import { debugPolen } from '#singletons/debug'
 import { Cache } from '@wollybeard/kit'
 import * as NodeFs from 'node:fs/promises'
 import * as NodePath from 'node:path'
-import type { NonEmptyChangeSets } from '../../schema/schema.js'
 import { polenVirtual } from '../vi.js'
 
 export const viProjectSchemaMetadata = polenVirtual([`project`, `schema-metadata`])
@@ -52,7 +52,9 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
 
     // Apply augmentations
     schemaResult.data.forEach(version => {
-      SchemaAugmentation.apply(version.after, config.schemaAugmentations)
+      if (version.after) {
+        SchemaAugmentation.apply(version.after.data, config.schemaAugmentations)
+      }
     })
 
     // Build metadata
@@ -103,9 +105,17 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
     })
   }
 
+  // Helper to create lifecycle data from schema data
+  const createLifecycleData = (
+    schemaData: GraphqlChangeset.ChangelogLinked,
+    metadata: Schema.SchemaMetadata,
+  ): SchemaLifecycle.SchemaLifecycle => {
+    return SchemaLifecycle.create(schemaData)
+  }
+
   // Helper to write assets using schema-source API
   const writeDevAssets = async (
-    schemaData: NonEmptyChangeSets,
+    schemaData: GraphqlChangeset.ChangelogLinked,
     metadata: Schema.SchemaMetadata,
   ) => {
     // schemaData is now guaranteed to be non-null NonEmptyChangeSets
@@ -113,8 +123,10 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
     const devAssetsDir = config.paths.framework.devAssets.schemas
     await NodeFs.mkdir(devAssetsDir, { recursive: true })
 
+    const lifecycle = createLifecycleData(schemaData, metadata)
+
     const schemaSource = createDevSchemaSource(metadata)
-    await schemaSource.writeAllAssets(schemaData, metadata)
+    await schemaSource.writeAllAssets(schemaData, metadata, lifecycle)
     debug(`devAssetsWritten`, { versionCount: schemaData.length })
   }
 
@@ -288,8 +300,10 @@ export const SchemaAssets = (config: Config.Config): Vite.Plugin => {
         assetsPath: config.paths.framework.devAssets.absolute,
       })
 
+      const lifecycle = createLifecycleData(schemaData, metadata)
+
       // Emit all assets using the high-level API
-      await schemaSource.writeAllAssets(schemaData, metadata)
+      await schemaSource.writeAllAssets(schemaData, metadata, lifecycle)
       debug(`buildMode:allAssetsEmitted`, { versionCount: schemaData.length })
     },
 

package/src/api/vite/vi.ts

@@ -1,4 +1,4 @@
-import { ViteVirtual } from '#lib/vite-virtual/index'
+import { ViteVirtual } from '#lib/vite-virtual'
 
 export const polenVirtual = ViteVirtual.Identifier.createFactory({
   namespace: `polen`,

package/src/cli/commands/cache/$default.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+console.error(`Usage: polen cache <command>
+
+Commands:
+  delete    Delete all Polen-generated caches
+  show      Display information about Polen caches
+`)
+
+process.exit(1)

package/src/cli/commands/cache/delete.ts

@@ -0,0 +1,27 @@
+import { Api } from '#api/index'
+import { projectParameter } from '#cli/_/parameters'
+import { ensureOptionalAbsoluteWithCwd } from '#lib/kit-temp'
+import { Command } from '@molt/command'
+import consola from 'consola'
+
+const args = Command.create()
+  .parameter(
+    `--project -p`,
+    projectParameter,
+  )
+  .settings({
+    parameters: {
+      environment: {
+        $default: {
+          prefix: `POLEN_CACHE_`,
+          enabled: false,
+        },
+      },
+    },
+  })
+  .parse()
+
+const dir = ensureOptionalAbsoluteWithCwd(args.project)
+
+await Api.Cache.deleteAll(dir)
+consola.success(`Polen caches deleted`)

package/src/cli/commands/cache/show.ts

@@ -0,0 +1,99 @@
+import { Api } from '#api/index'
+import { Command } from '@molt/command'
+import { z } from 'zod'
+
+const args = Command.create()
+  .parameter(
+    `--depth -d`,
+    z.number().min(0).max(5).default(2).describe(`Maximum depth for directory tree display`),
+  )
+  .settings({
+    parameters: {
+      environment: {
+        $default: {
+          prefix: `POLEN_CACHE_`,
+          enabled: false,
+        },
+      },
+    },
+  })
+  .parse()
+
+// Helper to format bytes
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+// Helper to render directory tree
+const renderTree = (nodes: Api.Cache.TreeNode[], prefix = ``, isLast = true): string[] => {
+  const lines: string[] = []
+
+  nodes.forEach((node, index) => {
+    const isLastNode = index === nodes.length - 1
+    const connector = isLastNode ? `└─` : `├─`
+    const extension = isLastNode ? `  ` : `│ `
+
+    let line = `${prefix}${connector} ${node.name}`
+    if (node.type === `file` && node.size !== undefined) {
+      line += ` (${formatBytes(node.size)})`
+    }
+    lines.push(line)
+
+    if (node.children && node.children.length > 0) {
+      const childLines = renderTree(node.children, prefix + extension, isLastNode)
+      lines.push(...childLines)
+    }
+  })
+
+  return lines
+}
+
+// Get cache info
+const info = await Api.Cache.info({ depth: args.depth })
+
+console.log(`Root: ${info.rootPath}`)
+console.log()
+
+// Development assets
+console.log(`Development assets: ${info.developmentAssets.path.replace(info.rootPath + `/`, ``)}`)
+if (info.developmentAssets.exists) {
+  const size = info.developmentAssets.size ? ` (${formatBytes(info.developmentAssets.size)})` : ``
+  console.log(`  Status: exists${size}`)
+
+  if (info.developmentAssets.tree && info.developmentAssets.tree.length > 0) {
+    console.log(`  Contents:`)
+    const treeLines = renderTree(info.developmentAssets.tree, `    `)
+    treeLines.forEach(line => console.log(line))
+  }
+} else {
+  console.log(`  Status: empty`)
+}
+
+console.log()
+
+// Vite cache
+console.log(`Vite:`)
+if (info.vite.exists) {
+  const size = info.vite.size ? ` (${formatBytes(info.vite.size)})` : ``
+  console.log(`  Status: exists${size}`)
+
+  if (info.vite.optimizedDependencies && info.vite.optimizedDependencies.length > 0) {
+    const deps = info.vite.optimizedDependencies
+    const showing = Math.min(10, deps.length)
+    const more = deps.length - showing
+
+    console.log(`  Optimized dependencies (${deps.length}):`)
+    deps.slice(0, showing).forEach(dep => {
+      console.log(`    ${dep.name} (${formatBytes(dep.size)})`)
+    })
+
+    if (more > 0) {
+      console.log(`    ... (${more} more)`)
+    }
+  }
+} else {
+  console.log(`  Status: empty`)
+}

package/src/cli/commands/cache.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { Cli, Path } from '@wollybeard/kit'
+
+// Remove the "cache" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
+const commandsDir = Path.join(import.meta.dirname, `cache`)
+await Cli.dispatch(commandsDir)

package/src/cli/commands/config.ts

@@ -2,5 +2,8 @@
 
 import { Cli, Path } from '@wollybeard/kit'
 
+// Remove the "config" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
 const commandsDir = Path.join(import.meta.dirname, `config`)
 await Cli.dispatch(commandsDir)

package/src/cli/commands/open.ts

@@ -9,8 +9,8 @@
 
 import { Api } from '#api/index'
 import { Vite } from '#dep/vite/index'
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
 import { Command } from '@molt/command'
 import type { Fn } from '@wollybeard/kit'
 import { Err, Fs, Json, Path, Rec } from '@wollybeard/kit'

package/src/cli/commands/static.ts

@@ -2,5 +2,8 @@
 
 import { Cli, Path } from '@wollybeard/kit'
 
+// Remove the "static" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
 const commandsDir = Path.join(import.meta.dirname, `static`)
 await Cli.dispatch(commandsDir)

package/src/exports/polen.ts

@@ -1,3 +1,4 @@
 export { defineConfig } from '#api/config/config'
 export { type ConfigInput } from '#api/config/configurator'
+export { Hooks } from '#api/hooks/helpers'
 export { Main as VitePlugin } from '#api/vite/plugins/main'

package/src/exports/radix-ui/react-icons.ts

@@ -0,0 +1,3 @@
+// Re-export Radix UI icons that users might want to use in their navbar
+// This allows users to import from 'polen/radix-ui/react-icons' without installing @radix-ui/react-icons
+export * from '@radix-ui/react-icons'

package/src/exports/radix-ui/themes.ts

@@ -0,0 +1,3 @@
+// Re-export Radix UI themes that Polen uses internally
+// This allows users to import from 'polen/radix-ui/themes' without installing @radix-ui/themes
+export * from '@radix-ui/themes'

package/src/lib/errors/$.ts

@@ -0,0 +1 @@
+export * as Errors from './$$.js'

package/src/lib/file-router/$.ts

@@ -0,0 +1 @@
+export * as FileRouter from './$$.js'

package/src/lib/file-router/index.test.ts

@@ -1,7 +1,7 @@
 import { Fn } from '@wollybeard/kit'
 import { describe, expect } from 'vitest'
 import { test } from '../../../tests/unit/helpers/test.js'
-import { FileRouter } from './index.js'
+import { FileRouter } from './$.js'
 
 /* Note
 

package/src/lib/grafaid/$.ts

@@ -0,0 +1 @@
+export * as Grafaid from './$$.js'

package/src/lib/grafaid/schema/type.ts

@@ -3,6 +3,7 @@ import {
   type GraphQLInputObjectType,
   type GraphQLInterfaceType,
   type GraphQLList,
+  type GraphQLNamedType,
   type GraphQLNonNull,
   type GraphQLObjectType,
   type GraphQLScalarType,

package/src/lib/graphql-change/{graphql-change.ts → $$.ts}

@@ -1,5 +1,5 @@
 import { GraphqlInspector } from '#dep/graphql-inspector/index'
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import type { Change } from './change-types.js'
 
 export * from './change-types.js'

package/src/lib/graphql-change/$.ts

@@ -0,0 +1 @@
+export * as GraphqlChange from './$$.js'

package/src/lib/graphql-change/change-groups.ts

@@ -277,31 +277,61 @@ export type Type =
   | 'SchemaRootType'
   | 'DirectiveUsage'
 
-export const getType = (change: Change): Type => {
-  if (isTypeOperation(change)) return 'TypeOperation'
-  if (isTypeDescription(change)) return 'TypeDescription'
-  if (isFieldOperation(change)) return 'FieldOperation'
-  if (isFieldDescription(change)) return 'FieldDescription'
-  if (isFieldDeprecation(change)) return 'FieldDeprecation'
-  if (isFieldDeprecationReason(change)) return 'FieldDeprecationReason'
-  if (isFieldArgumentOperation(change)) return 'FieldArgumentOperation'
-  if (isFieldArgument(change)) return 'FieldArgument'
-  if (isFieldArgumentDescription(change)) return 'FieldArgumentDescription'
-  if (isEnumValueOperation(change)) return 'EnumValueOperation'
-  if (isEnumValueDescription(change)) return 'EnumValueDescription'
-  if (isEnumValueDeprecationReason(change)) return 'EnumValueDeprecationReason'
-  if (isInputFieldOperation(change)) return 'InputFieldOperation'
-  if (isInputFieldDescription(change)) return 'InputFieldDescription'
-  if (isInputFieldDefaultValue(change)) return 'InputFieldDefaultValue'
-  if (isUnionMemberOperation(change)) return 'UnionMemberOperation'
-  if (isObjectTypeInterfaceOperation(change)) return 'ObjectTypeInterfaceOperation'
-  if (isDirectiveOperation(change)) return 'DirectiveOperation'
-  if (isDirectiveDescription(change)) return 'DirectiveDescription'
-  if (isDirectiveLocationOperation(change)) return 'DirectiveLocationOperation'
-  if (isDirectiveArgumentOperation(change)) return 'DirectiveArgumentOperation'
-  if (isDirectiveArgument(change)) return 'DirectiveArgument'
-  if (isDirectiveArgumentDescription(change)) return 'DirectiveArgumentDescription'
-  if (isSchemaRootType(change)) return 'SchemaRootType'
-  if (isDirectiveUsage(change)) return 'DirectiveUsage'
+/**
+ * Conditional type that maps each change type to its corresponding group type
+ */
+export type getType<$Change extends Change> = $Change extends TypeOperation ? 'TypeOperation'
+  : $Change extends TypeDescription ? 'TypeDescription'
+  : $Change extends FieldOperation ? 'FieldOperation'
+  : $Change extends FieldDescription ? 'FieldDescription'
+  : $Change extends FieldDeprecation ? 'FieldDeprecation'
+  : $Change extends FieldDeprecationReason ? 'FieldDeprecationReason'
+  : $Change extends FieldArgumentOperation ? 'FieldArgumentOperation'
+  : $Change extends FieldArgument ? 'FieldArgument'
+  : $Change extends FieldArgumentDescription ? 'FieldArgumentDescription'
+  : $Change extends EnumValueOperation ? 'EnumValueOperation'
+  : $Change extends EnumValueDescription ? 'EnumValueDescription'
+  : $Change extends EnumValueDeprecationReason ? 'EnumValueDeprecationReason'
+  : $Change extends InputFieldOperation ? 'InputFieldOperation'
+  : $Change extends InputFieldDescription ? 'InputFieldDescription'
+  : $Change extends InputFieldDefaultValue ? 'InputFieldDefaultValue'
+  : $Change extends UnionMemberOperation ? 'UnionMemberOperation'
+  : $Change extends ObjectTypeInterfaceOperation ? 'ObjectTypeInterfaceOperation'
+  : $Change extends DirectiveOperation ? 'DirectiveOperation'
+  : $Change extends DirectiveDescription ? 'DirectiveDescription'
+  : $Change extends DirectiveLocationOperation ? 'DirectiveLocationOperation'
+  : $Change extends DirectiveArgumentOperation ? 'DirectiveArgumentOperation'
+  : $Change extends DirectiveArgument ? 'DirectiveArgument'
+  : $Change extends DirectiveArgumentDescription ? 'DirectiveArgumentDescription'
+  : $Change extends SchemaRootType ? 'SchemaRootType'
+  : $Change extends DirectiveUsage ? 'DirectiveUsage'
+  : never
+
+export const getType = <change extends Change>(change: change): getType<change> => {
+  if (isTypeOperation(change)) return 'TypeOperation' as getType<change>
+  if (isTypeDescription(change)) return 'TypeDescription' as getType<change>
+  if (isFieldOperation(change)) return 'FieldOperation' as getType<change>
+  if (isFieldDescription(change)) return 'FieldDescription' as getType<change>
+  if (isFieldDeprecation(change)) return 'FieldDeprecation' as getType<change>
+  if (isFieldDeprecationReason(change)) return 'FieldDeprecationReason' as getType<change>
+  if (isFieldArgumentOperation(change)) return 'FieldArgumentOperation' as getType<change>
+  if (isFieldArgument(change)) return 'FieldArgument' as getType<change>
+  if (isFieldArgumentDescription(change)) return 'FieldArgumentDescription' as getType<change>
+  if (isEnumValueOperation(change)) return 'EnumValueOperation' as getType<change>
+  if (isEnumValueDescription(change)) return 'EnumValueDescription' as getType<change>
+  if (isEnumValueDeprecationReason(change)) return 'EnumValueDeprecationReason' as getType<change>
+  if (isInputFieldOperation(change)) return 'InputFieldOperation' as getType<change>
+  if (isInputFieldDescription(change)) return 'InputFieldDescription' as getType<change>
+  if (isInputFieldDefaultValue(change)) return 'InputFieldDefaultValue' as getType<change>
+  if (isUnionMemberOperation(change)) return 'UnionMemberOperation' as getType<change>
+  if (isObjectTypeInterfaceOperation(change)) return 'ObjectTypeInterfaceOperation' as getType<change>
+  if (isDirectiveOperation(change)) return 'DirectiveOperation' as getType<change>
+  if (isDirectiveDescription(change)) return 'DirectiveDescription' as getType<change>
+  if (isDirectiveLocationOperation(change)) return 'DirectiveLocationOperation' as getType<change>
+  if (isDirectiveArgumentOperation(change)) return 'DirectiveArgumentOperation' as getType<change>
+  if (isDirectiveArgument(change)) return 'DirectiveArgument' as getType<change>
+  if (isDirectiveArgumentDescription(change)) return 'DirectiveArgumentDescription' as getType<change>
+  if (isSchemaRootType(change)) return 'SchemaRootType' as getType<change>
+  if (isDirectiveUsage(change)) return 'DirectiveUsage' as getType<change>
   neverCase(change)
 }

package/src/lib/graphql-changeset/$$.ts

@@ -0,0 +1,3 @@
+export * from './changelog.js'
+export * from './changeset.js'
+export * from './versioned-schema.js'

package/src/lib/graphql-changeset/$.ts

@@ -0,0 +1 @@
+export * as GraphqlChangeset from './$$.js'

package/src/lib/graphql-changeset/changelog.ts

@@ -0,0 +1,9 @@
+import type { ChangeSet, ChangeSetLinked } from './changeset.js'
+
+// Changelog
+
+export type Changelog = [ChangeSet, ...ChangeSet[]]
+
+// Linked
+
+export type ChangelogLinked = [ChangeSetLinked, ...ChangeSetLinked[]]

package/src/lib/graphql-changeset/changeset.ts

@@ -0,0 +1,190 @@
+import type { GrafaidOld } from '#lib/grafaid-old'
+import type { GraphqlChange } from '#lib/graphql-change'
+import type { GraphQLSchema } from 'graphql'
+import { SuperJSON } from 'superjson'
+import type { VersionableSchema, VersionableSchemaLinked } from './versioned-schema.js'
+
+const superjson = new SuperJSON()
+
+superjson.registerCustom({
+  isApplicable: (v): v is GraphQLSchema => v?.constructor?.name === 'GraphQLSchema',
+  serialize: () => null,
+  deserialize: () => null,
+}, 'GraphQLSchema')
+
+// ChangeSet
+
+export type ChangeSet = IntermediateChangeSet | InitialChangeSet
+
+export interface IntermediateChangeSet {
+  type: 'IntermediateChangeSet'
+  changes: GraphqlChange.Change[]
+  date: Date
+  after: VersionableSchema
+  before: VersionableSchema
+}
+
+export interface InitialChangeSet {
+  type: 'InitialChangeSet'
+  date: Date
+  after: VersionableSchema
+}
+
+// Linked
+
+export type ChangeSetLinked = InitialChangeSetLinked | IntermediateChangeSetLinked
+
+export interface IntermediateChangeSetLinked extends IntermediateChangeSet {
+  after: VersionableSchemaLinked
+  before: VersionableSchemaLinked
+}
+
+export interface InitialChangeSetLinked extends InitialChangeSet {
+  after: VersionableSchemaLinked
+}
+
+// Predicate Functions
+
+/**
+ * Type guard to check if a value is any type of ChangeSet
+ */
+export const isChangeSet = (value: unknown): value is ChangeSet => {
+  return value !== null
+    && typeof value === 'object'
+    && 'type' in value
+    && ((value as any).type === 'InitialChangeSet' || (value as any).type === 'IntermediateChangeSet')
+}
+
+/**
+ * Type guard to check if a changeset is an InitialChangeSet
+ */
+export const isInitialChangeSet = (changeSet: ChangeSet): changeSet is InitialChangeSet => {
+  return changeSet.type === 'InitialChangeSet'
+}
+
+/**
+ * Type guard to check if a changeset is an IntermediateChangeSet
+ */
+export const isIntermediateChangeSet = (changeSet: ChangeSet): changeSet is IntermediateChangeSet => {
+  return changeSet.type === 'IntermediateChangeSet'
+}
+
+/**
+ * Type guard to check if a linked changeset is an InitialChangeSetLinked
+ */
+export const isInitialChangeSetLinked = (changeSet: ChangeSetLinked): changeSet is InitialChangeSetLinked => {
+  return changeSet.type === 'InitialChangeSet'
+}
+
+/**
+ * Type guard to check if a linked changeset is an IntermediateChangeSetLinked
+ */
+export const isIntermediateChangeSetLinked = (changeSet: ChangeSetLinked): changeSet is IntermediateChangeSetLinked => {
+  return changeSet.type === 'IntermediateChangeSet'
+}
+
+/**
+ * Type guard to check if a changeset is linked (has schema data)
+ */
+export const isLinked = (changeSet: ChangeSet | ChangeSetLinked): changeSet is ChangeSetLinked => {
+  if (isInitialChangeSet(changeSet)) {
+    return changeSet.after.data !== null
+  } else {
+    return changeSet.after.data !== null && changeSet.before.data !== null
+  }
+}
+
+// JSON Codecs
+
+/**
+ * Convert an unlinked changeset to linked by adding schema references
+ */
+export const link = (
+  changeset: ChangeSet,
+  schemaResolver: (version: string | null) => GrafaidOld.Schema.Schema | null,
+): ChangeSetLinked => {
+  if (isInitialChangeSet(changeset)) {
+    const afterSchema = schemaResolver(changeset.after.version)
+    if (!afterSchema) {
+      throw new Error(`Unable to resolve schema for version: ${changeset.after.version}`)
+    }
+    return {
+      type: 'InitialChangeSet',
+      date: changeset.date,
+      after: {
+        version: changeset.after.version,
+        data: afterSchema,
+      },
+    }
+  } else {
+    const afterSchema = schemaResolver(changeset.after.version)
+    const beforeSchema = schemaResolver(changeset.before.version)
+    if (!afterSchema || !beforeSchema) {
+      throw new Error(
+        `Unable to resolve schemas for versions: after=${changeset.after.version}, before=${changeset.before.version}`,
+      )
+    }
+    return {
+      type: 'IntermediateChangeSet',
+      changes: changeset.changes,
+      date: changeset.date,
+      after: {
+        version: changeset.after.version,
+        data: afterSchema,
+      },
+      before: {
+        version: changeset.before.version,
+        data: beforeSchema,
+      },
+    }
+  }
+}
+
+/**
+ * Convert a linked changeset to unlinked by removing schema references
+ */
+// export const unlink = (changeset: ChangeSetLinked): ChangeSet => {
+//   if (isInitialChangeSetLinked(changeset)) {
+//     return {
+//       type: 'InitialChangeSet',
+//       date: changeset.date,
+//       after: {
+//         version: changeset.after.version,
+//         data: null,
+//       },
+//     }
+//   } else {
+//     return {
+//       type: 'IntermediateChangeSet',
+//       changes: changeset.changes,
+//       date: changeset.date,
+//       after: {
+//         version: changeset.after.version,
+//         data: null,
+//       },
+//       before: {
+//         version: changeset.before.version,
+//         data: null,
+//       },
+//     }
+//   }
+// }
+
+/**
+ * Convert a changeset to JSON string (handles both linked and unlinked)
+ */
+export const toJson = (changeset: ChangeSet, options?: { pretty?: boolean }): string => {
+  const isPretty = options?.pretty ?? true
+  if (isPretty) {
+    const serialized = superjson.serialize(changeset)
+    return JSON.stringify(serialized, null, 2)
+  }
+  return superjson.stringify(changeset)
+}
+
+/**
+ * Parse changeset from JSON string
+ */
+export const fromJson = (json: string): ChangeSet => {
+  return superjson.parse(json)
+}

package/src/lib/graphql-changeset/versioned-schema.ts

@@ -0,0 +1,43 @@
+import type { GrafaidOld } from '#lib/grafaid-old'
+
+// VersionableSchema
+
+export interface VersionableSchema {
+  /**
+   * `null` if schema is not versioned.
+   */
+  version: string | null
+  /**
+   * `null` if schema has not been hydrated.
+   * Something external is resonsible for linking this.
+   * It should use `version` if not null to get the correct schema somehow.
+   * If `version` is null, it should use some schema singleton.
+   */
+  data: GrafaidOld.Schema.Schema | null
+}
+
+export interface VersionableSchemaUnlinked {
+  version: string | null
+  data: null
+}
+
+export interface VersionableSchemaLinked {
+  version: string | null
+  data: GrafaidOld.Schema.Schema
+}
+
+// Predicate Functions
+
+/**
+ * Type guard to check if a schema is linked (has data)
+ */
+export const isVersionableSchemaLinked = (schema: VersionableSchema): schema is VersionableSchemaLinked => {
+  return schema.data !== null
+}
+
+/**
+ * Type guard to check if a schema is unlinked (no data)
+ */
+export const isVersionableSchemaUnlinked = (schema: VersionableSchema): schema is VersionableSchemaUnlinked => {
+  return schema.data === null
+}