@graphprotocol/hypergraph 0.0.14 → 0.2.0

package/dist/mapping/Mapping.d.ts

@@ -0,0 +1,418 @@
+import { type CreatePropertyParams, Id as Grc20Id, type Op } from '@graphprotocol/grc-20';
+import { Schema as EffectSchema } from 'effect';
+/**
+ * Mappings for a schema type and its properties/relations
+ *
+ * @since 0.2.0
+ */
+export type MappingEntry = {
+    /**
+     * Array of the `Id.Id` of the type in the Knowledge Graph.
+     * Is an array because a type can belong to multiple spaces/extend multiple types.
+     *
+     * @since 0.2.0
+     */
+    typeIds: Array<Grc20Id.Id>;
+    /**
+     * Record of property names to the `Id.Id` of the type in the Knowledge Graph
+     *
+     * @since 0.2.0
+     */
+    properties?: {
+        [key: string]: Grc20Id.Id;
+    } | undefined;
+    /**
+     * Record of relation properties to the `Id.Id` of the type in the Knowledge Graph
+     *
+     * @since 0.2.0
+     */
+    relations?: {
+        [key: string]: Grc20Id.Id;
+    } | undefined;
+};
+/**
+ * @example
+ * ```ts
+ * import { Id } from '@graphprotocol/grc-20'
+ * import type { Mapping } from '@graphprotocol/hypergraph/mapping'
+ *
+ * const mapping: Mapping = {
+ *   Account: {
+ *     typeIds: [Id.Id('a5fd07b1-120f-46c6-b46f-387ef98396a6')],
+ *     properties: {
+ *       username: Id.Id('994edcff-6996-4a77-9797-a13e5e3efad8'),
+ *       createdAt: Id.Id('64bfba51-a69b-4746-be4b-213214a879fe')
+ *     }
+ *   },
+ *   Event: {
+ *     typeIds: [Id.Id('0349187b-526f-435f-b2bb-9e9caf23127a')],
+ *     properties: {
+ *       name: Id.Id('3808e060-fb4a-4d08-8069-35b8c8a1902b'),
+ *       description: Id.Id('1f0d9007-8da2-4b28-ab9f-3bc0709f4837'),
+ *     },
+ *     relations: {
+ *       speaker: Id.Id('a5fd07b1-120f-46c6-b46f-387ef98396a6')
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @since 0.2.0
+ */
+export type Mapping = {
+    [key: string]: MappingEntry;
+};
+/**
+ * @since 0.2.0
+ */
+export type DataTypeRelation = `Relation(${string})`;
+/**
+ * @since 0.2.0
+ */
+export declare function isDataTypeRelation(val: string): val is DataTypeRelation;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaDataTypeRelation: EffectSchema.refine<`Relation(${string})`, EffectSchema.Schema<string, string, never>>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaDataTypeRelation = typeof SchemaDataTypeRelation.Type;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaDataTypePrimitive: EffectSchema.Literal<["Text", "Number", "Checkbox", "Date", "Point"]>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaDataTypePrimitive = typeof SchemaDataTypePrimitive.Type;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaDataType: EffectSchema.Union<[EffectSchema.Literal<["Text", "Number", "Checkbox", "Date", "Point"]>, EffectSchema.refine<`Relation(${string})`, EffectSchema.Schema<string, string, never>>]>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaDataType = typeof SchemaDataType.Type;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaTypePropertyRelation: EffectSchema.Struct<{
+    name: typeof EffectSchema.NonEmptyTrimmedString;
+    knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+    dataType: EffectSchema.refine<`Relation(${string})`, EffectSchema.Schema<string, string, never>>;
+    relationType: EffectSchema.refine<string, typeof EffectSchema.Trimmed>;
+}>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaTypePropertyRelation = typeof SchemaTypePropertyRelation.Type;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaTypePropertyPrimitive: EffectSchema.Struct<{
+    name: typeof EffectSchema.NonEmptyTrimmedString;
+    knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+    dataType: EffectSchema.Literal<["Text", "Number", "Checkbox", "Date", "Point"]>;
+}>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaTypePropertyPrimitive = typeof SchemaTypePropertyPrimitive.Type;
+/**
+ * @since 0.2.0
+ */
+export declare function propertyIsRelation(property: SchemaTypePropertyPrimitive | SchemaTypePropertyRelation): property is SchemaTypePropertyRelation;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaType: EffectSchema.Struct<{
+    name: typeof EffectSchema.NonEmptyTrimmedString;
+    knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+    properties: EffectSchema.filter<EffectSchema.filter<EffectSchema.Array$<EffectSchema.Union<[EffectSchema.Struct<{
+        name: typeof EffectSchema.NonEmptyTrimmedString;
+        knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+        dataType: EffectSchema.Literal<["Text", "Number", "Checkbox", "Date", "Point"]>;
+    }>, EffectSchema.Struct<{
+        name: typeof EffectSchema.NonEmptyTrimmedString;
+        knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+        dataType: EffectSchema.refine<`Relation(${string})`, EffectSchema.Schema<string, string, never>>;
+        relationType: EffectSchema.refine<string, typeof EffectSchema.Trimmed>;
+    }>]>>>>;
+}>;
+/**
+ * @since 0.2.0
+ */
+export type SchemaType = typeof SchemaType.Type;
+/**
+ * Represents the user-built schema object to generate a `Mappings` definition for
+ *
+ * @since 0.2.0
+ */
+export declare const Schema: EffectSchema.Struct<{
+    types: EffectSchema.filter<EffectSchema.filter<EffectSchema.filter<EffectSchema.Array$<EffectSchema.Struct<{
+        name: typeof EffectSchema.NonEmptyTrimmedString;
+        knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+        properties: EffectSchema.filter<EffectSchema.filter<EffectSchema.Array$<EffectSchema.Union<[EffectSchema.Struct<{
+            name: typeof EffectSchema.NonEmptyTrimmedString;
+            knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+            dataType: EffectSchema.Literal<["Text", "Number", "Checkbox", "Date", "Point"]>;
+        }>, EffectSchema.Struct<{
+            name: typeof EffectSchema.NonEmptyTrimmedString;
+            knowledgeGraphId: EffectSchema.NullOr<typeof EffectSchema.UUID>;
+            dataType: EffectSchema.refine<`Relation(${string})`, EffectSchema.Schema<string, string, never>>;
+            relationType: EffectSchema.refine<string, typeof EffectSchema.Trimmed>;
+        }>]>>>>;
+    }>>>>>;
+}>;
+/**
+ * @since 0.2.0
+ */
+export type Schema = typeof Schema.Type;
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaKnownDecoder: (i: {
+    readonly types: readonly {
+        readonly name: string;
+        readonly knowledgeGraphId: string | null;
+        readonly properties: readonly ({
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: string;
+            readonly relationType: string;
+        } | {
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: "Date" | "Text" | "Number" | "Checkbox" | "Point";
+        })[];
+    }[];
+}, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
+    readonly types: readonly {
+        readonly name: string;
+        readonly knowledgeGraphId: string | null;
+        readonly properties: readonly ({
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: `Relation(${string})`;
+            readonly relationType: string;
+        } | {
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: "Date" | "Text" | "Number" | "Checkbox" | "Point";
+        })[];
+    }[];
+};
+/**
+ * @since 0.2.0
+ */
+export declare const SchemaUnknownDecoder: (u: unknown, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
+    readonly types: readonly {
+        readonly name: string;
+        readonly knowledgeGraphId: string | null;
+        readonly properties: readonly ({
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: `Relation(${string})`;
+            readonly relationType: string;
+        } | {
+            readonly name: string;
+            readonly knowledgeGraphId: string | null;
+            readonly dataType: "Date" | "Text" | "Number" | "Checkbox" | "Point";
+        })[];
+    }[];
+};
+/**
+ * Iterate through all properties in all types in the schema of `dataType` === `Relation(${string})`
+ * and validate that the schema.types have a type for the existing relation
+ *
+ * @example <caption>All types exist</caption>
+ * ```ts
+ * import { allRelationPropertyTypesExist, type Mapping } from '@graphprotocol/hypergraph/mapping'
+ *
+ * const types: Mapping['types'] = [
+ *   {
+ *     name: "Account",
+ *     knowledgeGraphId: null,
+ *     properties: [
+ *       {
+ *         name: "username",
+ *         dataType: "Text",
+ *         knowledgeGraphId: null
+ *       }
+ *     ]
+ *   },
+ *   {
+ *     name: "Event",
+ *     knowledgeGraphId: null,
+ *     properties: [
+ *       {
+ *         name: "speaker",
+ *         dataType: "Relation(Account)"
+ *         relationType: "Account",
+ *         knowledgeGraphId: null,
+ *       }
+ *     ]
+ *   }
+ * ]
+ * expect(allRelationPropertyTypesExist(types)).toEqual(true)
+ * ```
+ *
+ * @example <caption>Account type is missing</caption>
+ * ```ts
+ * import { allRelationPropertyTypesExist, type Mapping } from '@graphprotocol/hypergraph/mapping'
+ *
+ * const types: Mapping['types'] = [
+ *   {
+ *     name: "Event",
+ *     knowledgeGraphId: null,
+ *     properties: [
+ *       {
+ *         name: "speaker",
+ *         dataType: "Relation(Account)",
+ *         relationType: "Account",
+ *         knowledgeGraphId: null,
+ *       }
+ *     ]
+ *   }
+ * ]
+ * expect(allRelationPropertyTypesExist(types)).toEqual(false)
+ * ```
+ *
+ * @since 0.2.0
+ *
+ * @param types the user-submitted schema types
+ */
+export declare function allRelationPropertyTypesExist(types: ReadonlyArray<SchemaType>): boolean;
+export type GenerateMappingResult = [mapping: Mapping, ops: ReadonlyArray<Op>];
+/**
+ * Takes the user-submitted schema, validates it, and build the `Mapping` definition for the schema as well as the GRC-20 Ops needed to publish the schema/schema changes to the Knowledge Graph.
+ *
+ * @example
+ * ```ts
+ * import { Id } from "@graphprotocol/grc-20"
+ * import { generateMapping } from "@graphprotocol/typesync"
+ *
+ * const schema: Schema = {
+ *   types: [
+ *     {
+ *       name: "Account",
+ *       knowledgeGraphId: "a5fd07b1-120f-46c6-b46f-387ef98396a6",
+ *       properties: [
+ *         {
+ *           name: "username",
+ *           dataType: "Text",
+ *           knowledgeGraphId: "994edcff-6996-4a77-9797-a13e5e3efad8"
+ *         },
+ *         {
+ *           name: "createdAt",
+ *           dataType: "Date",
+ *           knowledgeGraphId: null
+ *         }
+ *       ]
+ *     },
+ *     {
+ *       name: "Event",
+ *       knowledgeGraphId: null,
+ *       properties: [
+ *         {
+ *           name: "name",
+ *           dataType: "Text",
+ *           knowledgeGraphId: "3808e060-fb4a-4d08-8069-35b8c8a1902b"
+ *         },
+ *         {
+ *           name: "description",
+ *           dataType: "Text",
+ *           knowledgeGraphId: null
+ *         },
+ *         {
+ *           name: "speaker",
+ *           dataType: "Relation(Account)",
+ *           relationType: "Account",
+ *           knowledgeGraphId: null
+ *         }
+ *       ]
+ *     }
+ *   ],
+ * }
+ * const [mapping, ops] = generateMapping(schema)
+ *
+ * expect(mapping).toEqual({
+ *   Account: {
+ *     typeIds: [Id.Id("a5fd07b1-120f-46c6-b46f-387ef98396a6")], // comes from input schema
+ *     properties: {
+ *       username: Id.Id("994edcff-6996-4a77-9797-a13e5e3efad8"), // comes from input schema
+ *       createdAt: Id.Id("8cd7d9ac-a878-4287-8000-e71e6f853117"), // generated from Graph.createProperty Op
+ *     }
+ *   },
+ *   Event: {
+ *     typeIds: [Id.Id("20b3fe39-8e62-41a0-b9cb-92743fd760da")], // generated from Graph.createType Op
+ *     properties: {
+ *       name: Id.Id("3808e060-fb4a-4d08-8069-35b8c8a1902b"), // comes from input schema
+ *       description: Id.Id("8fc4e17c-7581-4d6c-a712-943385afc7b5"), // generated from Graph.createProperty Op
+ *     },
+ *     relations: {
+ *       speaker: Id.Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"), // generated from Graph.createProperty Op
+ *     }
+ *   }
+ * })
+ * expect(ops).toEqual([
+ *   // Graph.createProperty Op for Account.createdAt property
+ *   {
+ *     type: "CREATE_PROPERTY",
+ *     property: {
+ *       id: Id.Id("8cd7d9ac-a878-4287-8000-e71e6f853117"),
+ *       dataType: "TEXT"
+ *     }
+ *   },
+ *   // Graph.createProperty Op for Event.description property
+ *   {
+ *     type: "CREATE_PROPERTY",
+ *     property: {
+ *       id: Id.Id("8fc4e17c-7581-4d6c-a712-943385afc7b5"),
+ *       dataType: "TEXT"
+ *     }
+ *   },
+ *   // Graph.createProperty Op for Event.speaker property
+ *   {
+ *     type: "CREATE_PROPERTY",
+ *     property: {
+ *       id: Id.Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"),
+ *       dataType: "RELATION"
+ *     }
+ *   },
+ *   // Graph.createType Op for Event type
+ *   {
+ *     type: "CREATE_PROPERTY",
+ *     property: {
+ *       id: Id.Id("651ce59f-643b-4931-bf7a-5dc0ca0f5a47"),
+ *       dataType: "RELATION"
+ *     }
+ *   },
+ * ])
+ * ```
+ *
+ * @since 0.2.0
+ *
+ * @param input user-built and submitted schema
+ * @returns the generated [Mapping] definition from the submitted schema as well as the GRC-20 Ops required to publish the schema to the Knowledge Graph
+ */
+export declare function generateMapping(input: Schema): GenerateMappingResult;
+declare const RelationValueTypeDoesNotExistError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "/typesync/errors/RelationValueTypeDoesNotExistError";
+} & Readonly<A>;
+export declare class RelationValueTypeDoesNotExistError extends RelationValueTypeDoesNotExistError_base<{
+    readonly message: string;
+    readonly property: string;
+    readonly relatedType: string;
+}> {
+}
+/**
+ * @since 0.2.0
+ *
+ * @param dataType the dataType from the user-submitted schema
+ * @returns the mapped to GRC-20 dataType for the GRC-20 ops
+ */
+export declare function mapSchemaDataTypeToGRC20PropDataType(dataType: SchemaDataType): CreatePropertyParams['dataType'];
+export {};
+//# sourceMappingURL=Mapping.d.ts.map

package/dist/mapping/Mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mapping.d.ts","sourceRoot":"","sources":["../../src/mapping/Mapping.ts"],"names":[],"mappings":"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"}