@graphprotocol/hypergraph 0.3.0 → 0.4.1

package/src/cli/services/Typesync.ts

@@ -0,0 +1,189 @@
+import { FileSystem, Path } from '@effect/platform';
+import { NodeFileSystem } from '@effect/platform-node';
+import { AnsiDoc } from '@effect/printer-ansi';
+import { Cause, Data, Effect, Array as EffectArray, Option, Stream } from 'effect';
+import type { NonEmptyReadonlyArray } from 'effect/Array';
+import type { Schema as HypergraphSchema, Mapping } from '../../mapping/Mapping.js';
+import { parseHypergraphMapping, parseSchema } from './Utils.js';
+
+export class TypesyncSchemaStreamBuilder extends Effect.Service<TypesyncSchemaStreamBuilder>()(
+  '/Hypergraph/cli/services/TypesyncSchemaStreamBuilder',
+  {
+    dependencies: [NodeFileSystem.layer],
+    effect: Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+
+      const encoder = new TextEncoder();
+
+      const schemaCandidates = (cwd = '.') =>
+        EffectArray.make(
+          path.resolve(cwd, 'schema.ts'),
+          path.resolve(cwd, 'src/schema.ts'),
+          path.resolve(cwd, 'app/schema.ts'),
+          path.resolve(cwd, 'src/app/schema.ts'),
+          // @todo other possible locations?
+        );
+      const mappingCandidates = (cwd = '.') =>
+        EffectArray.make(
+          path.resolve(cwd, 'mapping.ts'),
+          path.resolve(cwd, 'src/mapping.ts'),
+          path.resolve(cwd, 'app/mapping.ts'),
+          path.resolve(cwd, 'src/app/mapping.ts'),
+          // @todo other possible locations?
+        );
+
+      const jiti = yield* Effect.tryPromise({
+        async try() {
+          const { createJiti } = await import('jiti');
+          return createJiti(import.meta.url, { moduleCache: false, tryNative: false });
+        },
+        catch(cause) {
+          return new MappingLoaderError({ cause });
+        },
+      }).pipe(Effect.cached);
+
+      const loadMapping = Effect.fnUntraced(function* (mappingFilePath: string) {
+        return yield* Effect.tryMapPromise(jiti, {
+          try(instance) {
+            return instance.import(mappingFilePath);
+          },
+          catch(cause) {
+            return cause;
+          },
+        }).pipe(
+          Effect.map(parseHypergraphMapping),
+          Effect.mapError(
+            (cause) => new MappingLoaderError({ cause, message: `Failed to load mapping file ${mappingFilePath}` }),
+          ),
+          Effect.tapErrorCause((cause) =>
+            Effect.logWarning(
+              AnsiDoc.cats([AnsiDoc.text('Failure loading mapping'), AnsiDoc.text(Cause.pretty(cause))]),
+            ),
+          ),
+          Effect.orElseSucceed(() => ({}) as Mapping),
+        );
+      });
+
+      const findHypergraphSchema = Effect.fnUntraced(function* (candidates: NonEmptyReadonlyArray<string>) {
+        return yield* Effect.findFirst(candidates, (_) => fs.exists(_).pipe(Effect.orElseSucceed(() => false)));
+      });
+
+      /**
+       * Reads the schema.ts file, and maybe reads the mapping.ts file (if exists).
+       * Parses the schema and from it, plus the loaded mapping, creates a Stream of the Hypergraph [Schema](../../mapping/Mapping.ts).
+       * This represents the state of the schema when the user hits the schema stream endpoint
+       *
+       * @param schemaFilePath path of the schema.ts file
+       * @param mappingFilePath [Optional] path of the mapping.ts file
+       * @returns A stream of [Schema](../../mapping/Mapping.ts) pared from the schema.ts file
+       */
+      const currentSchemaStream = (
+        schemaFilePath: Option.Option<string>,
+        mappingFilePath: Option.Option<string>,
+      ): Stream.Stream<HypergraphSchema, never, never> =>
+        Stream.fromEffect(
+          Effect.gen(function* () {
+            const schema = yield* Option.match(schemaFilePath, {
+              onNone: () => Effect.succeed(''),
+              onSome: fs.readFileString,
+            });
+            const mapping = yield* Option.match(mappingFilePath, {
+              onNone: () => Effect.succeed({} as Mapping),
+              onSome: loadMapping,
+            });
+            return yield* parseSchema(schema, mapping);
+          }),
+        ).pipe(
+          Stream.tapErrorCause((cause) =>
+            Effect.logError(
+              AnsiDoc.text('Failure parsing current schema into types'),
+              AnsiDoc.text(Cause.pretty(cause)),
+            ),
+          ),
+          // if failure, don't bubble to return and just return empty schema
+          Stream.orElseSucceed(() => ({ types: [] }) satisfies HypergraphSchema),
+        );
+      /**
+       * Reads the schema.ts file, and maybe reads the mapping.ts file (if exists).
+       * Parses the schema and from it, plus the loaded mapping, creates a Stream of the Hypergraph [Schema](../../mapping/Mapping.ts).
+       * This stream watches for changes in both the schema.ts file and (if provided) the mapping.ts file.
+       * This way, if the user updates either, this will emit an event on the stream of the updated schema.
+       *
+       * @param schemaFilePath path of the schema.ts file
+       * @param mappingFilePath [Optional] path of the mapping.ts file
+       * @returns A stream of [Schema](../../mapping/Mapping.ts) pared from the schema.ts file
+       */
+      const watchSchemaStream = (
+        schemaFilePath: Option.Option<string>,
+        mappingFilePath: Option.Option<string>,
+      ): Stream.Stream<HypergraphSchema, never, never> => {
+        const schemaWatch = Option.match(schemaFilePath, {
+          // @todo watch the root here so if a schema is created, it will get picked up
+          onNone: () => Stream.empty,
+          onSome: fs.watch,
+        });
+        const mappingWatch = Option.match(mappingFilePath, {
+          onNone: () => Stream.empty,
+          onSome: fs.watch,
+        });
+
+        return Stream.mergeAll([schemaWatch, mappingWatch], { concurrency: 2 }).pipe(
+          Stream.buffer({ capacity: 1, strategy: 'sliding' }),
+          Stream.mapEffect(() =>
+            Effect.gen(function* () {
+              const schema = yield* Option.match(schemaFilePath, {
+                onNone: () => Effect.succeed(''),
+                onSome: fs.readFileString,
+              });
+              const mapping = yield* Option.match(mappingFilePath, {
+                onNone: () => Effect.succeed({} as Mapping),
+                onSome: loadMapping,
+              });
+              return yield* parseSchema(schema, mapping);
+            }),
+          ),
+          Stream.tapErrorCause((cause) =>
+            Effect.logError(AnsiDoc.text('Failure parsing schema changes into types'), { cause: Cause.pretty(cause) }),
+          ),
+          // if failure, don't bubble to return and just return empty schema
+          Stream.orElseSucceed(() => ({ types: [] }) satisfies HypergraphSchema),
+        );
+      };
+
+      const hypergraphSchemaStream = (cwd = '.') =>
+        Effect.gen(function* () {
+          const schemaFileCandidates = schemaCandidates(cwd);
+          // Fetch the Schema definition from any schema.ts in the directory.
+          // If exists, use it to parse the Hypergraph schema
+          const schemaFilePath = yield* findHypergraphSchema(schemaFileCandidates);
+          if (Option.isNone(schemaFilePath)) {
+            yield* Effect.logDebug(
+              AnsiDoc.text('No Hypergraph schema file found. Searched:'),
+              AnsiDoc.cats(schemaFileCandidates.map((candidate) => AnsiDoc.text(candidate))),
+            );
+          }
+          // Fetch the Mapping definition from any mapping.ts in the directory.
+          // If exists, use it to get the knowledgeGraphId for each type/property in the parsed schema
+          const mappingFilePath = yield* findHypergraphSchema(mappingCandidates(cwd));
+
+          return currentSchemaStream(schemaFilePath, mappingFilePath).pipe(
+            Stream.concat(watchSchemaStream(schemaFilePath, mappingFilePath)),
+            Stream.map((stream) => {
+              const jsonData = JSON.stringify(stream);
+              const sseData = `data: ${jsonData}\n\n`;
+              return encoder.encode(sseData);
+            }),
+          );
+        });
+
+      return { hypergraphSchemaStream } as const;
+    }),
+  },
+) {}
+export const layer = TypesyncSchemaStreamBuilder.Default;
+
+export class MappingLoaderError extends Data.TaggedError('/Hypergraph/cli/errors/MappingLoaderError')<{
+  readonly cause: unknown;
+  readonly message?: string;
+}> {}

package/src/cli/services/Utils.ts

@@ -0,0 +1,187 @@
+import { Data, Effect, Array as EffectArray } from 'effect';
+import ts from 'typescript';
+
+import * as Mapping from '../../mapping/Mapping.js';
+import * as Utils from '../../mapping/Utils.js';
+
+/**
+ * Takes a parsed schema.ts file and maps it to a the Mapping.Schema type.
+ *
+ * @internal
+ *
+ * @param sourceCode the read schema.ts file
+ * @param mapping the parsed mappint.ts file
+ * @returns the parsed Schema instance
+ */
+export const parseSchema = (
+  sourceCode: string,
+  mapping: Mapping.Mapping,
+): Effect.Effect<Mapping.Schema, SchemaParserFailure> =>
+  Effect.try({
+    try() {
+      const sourceFile = ts.createSourceFile('schema.ts', sourceCode, ts.ScriptTarget.Latest, true);
+
+      const entities: Array<Mapping.SchemaType> = [];
+
+      const visit = (node: ts.Node) => {
+        if (ts.isClassDeclaration(node) && node.name) {
+          const className = node.name.text;
+          const properties: Array<Mapping.SchemaTypePropertyPrimitive | Mapping.SchemaTypePropertyRelation> = [];
+
+          // Find the Entity.Class call
+          if (node.heritageClauses) {
+            for (const clause of node.heritageClauses) {
+              for (const type of clause.types) {
+                if (ts.isCallExpression(type.expression)) {
+                  const callExpr = type.expression;
+
+                  // Look for the object literal with properties
+                  if (callExpr.arguments.length > 0) {
+                    const arg = callExpr.arguments[0];
+                    if (ts.isObjectLiteralExpression(arg)) {
+                      for (const prop of arg.properties) {
+                        if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                          const propName = prop.name.text;
+                          let dataType: Mapping.SchemaDataType = 'String';
+                          let relationType: string | undefined;
+
+                          const mappingEntry = mapping[className];
+                          const camelCasePropName = Utils.toCamelCase(propName);
+
+                          // Extract the type
+                          if (ts.isPropertyAccessExpression(prop.initializer)) {
+                            // Simple types like Type.Text
+                            dataType = Mapping.getDataType(prop.initializer.name.text);
+
+                            // Look up the property's knowledgeGraphId from the mapping
+                            const propKnowledgeGraphId = mappingEntry?.properties?.[camelCasePropName] || null;
+
+                            // push to type properties as primitive property
+                            properties.push({
+                              name: propName,
+                              dataType: dataType as Mapping.SchemaDataTypePrimitive,
+                              knowledgeGraphId: propKnowledgeGraphId,
+                            } satisfies Mapping.SchemaTypePropertyPrimitive);
+                          } else if (ts.isCallExpression(prop.initializer)) {
+                            // Relation types like Type.Relation(User)
+                            const callNode = prop.initializer;
+                            if (ts.isPropertyAccessExpression(callNode.expression)) {
+                              const typeName = callNode.expression.name.text;
+
+                              if (typeName === 'Relation' && callNode.arguments.length > 0) {
+                                const relationArg = callNode.arguments[0];
+                                if (ts.isIdentifier(relationArg)) {
+                                  relationType = relationArg.text;
+                                  dataType = `Relation(${relationType})`;
+
+                                  // Look up the relation property's knowledgeGraphId from the mapping
+                                  const relKnowledgeGraphId = mappingEntry?.relations?.[camelCasePropName] || null;
+
+                                  // push to type properties as relation property
+                                  properties.push({
+                                    name: propName,
+                                    dataType,
+                                    relationType,
+                                    knowledgeGraphId: relKnowledgeGraphId,
+                                  } satisfies Mapping.SchemaTypePropertyRelation);
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          // Look up the type's knowledgeGraphId from the mapping
+          const mappingEntry = mapping[Utils.toPascalCase(className)];
+          const typeKnowledgeGraphId = mappingEntry?.typeIds?.[0] ? mappingEntry.typeIds[0] : null;
+
+          entities.push({ name: className, knowledgeGraphId: typeKnowledgeGraphId, properties });
+        }
+
+        ts.forEachChild(node, visit);
+      };
+
+      visit(sourceFile);
+
+      return {
+        types: entities,
+      } as const;
+    },
+    catch(error) {
+      return new SchemaParserFailure({
+        message: `Failed to parse schema: ${error}`,
+        cause: error,
+      });
+    },
+  });
+
+export class SchemaParserFailure extends Data.TaggedError('/Hypergraph/cli/errors/SchemaParserFailure')<{
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
+
+/**
+ * @internal
+ *
+ * Runtime check to see if a value looks like a Mapping
+ */
+function isMappingLike(value: unknown): value is Mapping.Mapping {
+  if (!value || typeof value !== 'object') return false;
+  return Object.values(value).every(
+    (entry) =>
+      entry &&
+      typeof entry === 'object' &&
+      'typeIds' in entry &&
+      // biome-ignore lint/suspicious/noExplicitAny: parsing so type unknown
+      EffectArray.isArray((entry as any).typeIds),
+  );
+}
+
+/**
+ * @internal
+ *
+ * Look at the exported object from the mapping.ts file loaded via jiti and try to pull out the hypergraph mapping.
+ * Default should be:
+ * ```typescript
+ * export const mapping: Mapping
+ * ```
+ * But this is not guaranteed. This function looks through the file to try to find it using some logical defaults/checks.
+ *
+ * @param moduleExport the object imported from jiti from the mapping.ts file
+ */
+// biome-ignore lint/suspicious/noExplicitAny: type should be import object from jiti
+export function parseHypergraphMapping(moduleExport: any): Mapping.Mapping {
+  // Handle null/undefined inputs
+  if (!moduleExport || typeof moduleExport !== 'object') {
+    return {} as Mapping.Mapping;
+  }
+
+  // Find all exports that look like Mapping objects
+  const mappingCandidates = Object.entries(moduleExport).filter(([, value]) => isMappingLike(value));
+
+  if (mappingCandidates.length === 0) {
+    return {} as Mapping.Mapping;
+  }
+
+  if (mappingCandidates.length === 1) {
+    return mappingCandidates[0][1] as Mapping.Mapping;
+  }
+
+  // Multiple candidates - prefer common names
+  const preferredNames = ['mapping', 'default', 'config'];
+  for (const preferredName of preferredNames) {
+    const found = mappingCandidates.find(([name]) => name === preferredName);
+    if (found) {
+      return found[1] as Mapping.Mapping;
+    }
+  }
+
+  // If no preferred names found, use the first one
+  return mappingCandidates[0][1] as Mapping.Mapping;
+}

package/src/cli/subcommands/typesync.ts

@@ -0,0 +1,93 @@
+import { createServer } from 'node:http';
+import { Command, Options } from '@effect/cli';
+import {
+  HttpApi,
+  HttpApiBuilder,
+  HttpApiEndpoint,
+  HttpApiError,
+  HttpApiGroup,
+  HttpApiSchema,
+  HttpMiddleware,
+  HttpServer,
+  HttpServerResponse,
+} from '@effect/platform';
+import { NodeHttpServer } from '@effect/platform-node';
+import { AnsiDoc } from '@effect/printer-ansi';
+import { Effect, Layer, Schema } from 'effect';
+import * as Typesync from '../services/Typesync.js';
+
+const hypergraphTypeSyncApi = HttpApi.make('HypergraphTypeSyncApi')
+  .add(
+    HttpApiGroup.make('SchemaStreamGroup')
+      .add(
+        // exposes an api endpoint at /api/vX/schema/events that is a stream of the current Schema parsed from the directory the hypergraph-cli tool is running in
+        HttpApiEndpoint.get('HypergraphSchemaEventStream')`/schema/events`
+          .addError(HttpApiError.InternalServerError)
+          .addSuccess(
+            Schema.String.pipe(
+              HttpApiSchema.withEncoding({
+                kind: 'Json',
+                contentType: 'text/event-stream',
+              }),
+            ),
+          ),
+      )
+      .prefix('/v1'),
+  )
+  .prefix('/api');
+
+const hypergraphTypeSyncApiLive = HttpApiBuilder.group(hypergraphTypeSyncApi, 'SchemaStreamGroup', (handlers) =>
+  handlers.handle('HypergraphSchemaEventStream', () =>
+    Effect.gen(function* () {
+      const schemaStream = yield* Typesync.TypesyncSchemaStreamBuilder;
+
+      const stream = yield* schemaStream
+        .hypergraphSchemaStream()
+        .pipe(Effect.catchAll(() => new HttpApiError.InternalServerError()));
+
+      return yield* HttpServerResponse.stream(stream, { contentType: 'text/event-stream' }).pipe(
+        HttpServerResponse.setHeaders({
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+        }),
+      );
+    }),
+  ),
+);
+
+const HypergraphTypeSyncApiLive = HttpApiBuilder.api(hypergraphTypeSyncApi).pipe(
+  Layer.provide(hypergraphTypeSyncApiLive),
+  Layer.provide(Typesync.layer),
+);
+
+const HypergraphTypeSyncApiLayer = HttpApiBuilder.serve(HttpMiddleware.logger).pipe(
+  Layer.provide(HttpApiBuilder.middlewareCors()),
+  Layer.provide(HypergraphTypeSyncApiLive),
+);
+
+export const typesync = Command.make('typesync', {
+  args: {
+    port: Options.integer('port').pipe(
+      Options.withAlias('p'),
+      Options.withDefault(3000),
+      Options.withDescription('The port to run the Hypergraph TypeSync studio server on. Default 3000'),
+    ),
+  },
+}).pipe(
+  Command.withDescription(
+    'Opens the TypeSync studio to help users build and publish their Hypergraph application schema',
+  ),
+  Command.withHandler(({ args }) =>
+    Effect.gen(function* () {
+      yield* HypergraphTypeSyncApiLayer.pipe(
+        HttpServer.withLogAddress,
+        Layer.provide(NodeHttpServer.layer(createServer, { port: args.port })),
+        Layer.tap(() =>
+          Effect.logInfo(AnsiDoc.text(`🎉 TypeSync studio started and running at http://localhost:${args.port}`)),
+        ),
+        Layer.launch,
+      );
+    }),
+  ),
+);

package/src/index.ts

@@ -1,3 +1,4 @@
+export { Id } from '@graphprotocol/grc-20';
 export * as Connect from './connect/index.js';
 export * as Entity from './entity/index.js';
 export * as Identity from './identity/index.js';