feat: add draft of first utlity functions

Author: nikgraf

index.ts

@@ -14,7 +14,11 @@ export * as ID from './src/id.js';
  *
  * @since 0.0.6
  */
-export { BASE58_ALLOWED_CHARS, decodeBase58ToUUID, encodeBase58 } from './src/core/base58.js';
+export {
+  BASE58_ALLOWED_CHARS,
+  decodeBase58ToUUID,
+  encodeBase58,
+} from './src/core/base58.js';
 
 export {
   getAcceptEditorArguments,
@@ -33,7 +37,7 @@ export {
  */
 export { Account } from './src/account.js';
 
-export { TextBlock, DataBlock, ImageBlock } from './src/blocks.js';
+export { DataBlock, ImageBlock, TextBlock } from './src/blocks.js';
 
 /**
  * This module provides utility functions for working with knowledge graph
@@ -69,7 +73,7 @@ export { GraphUrl } from './src/scheme.js';
 /**
  * Provides ids for commonly used entities across the Knowledge Graph.
  */
-export { SYSTEM_IDS, NETWORK_IDS, CONTENT_IDS } from './src/system-ids.js';
+export { CONTENT_IDS, NETWORK_IDS, SYSTEM_IDS } from './src/system-ids.js';
 
 export { getChecksumAddress } from './src/core/get-checksum-address.js';
 
@@ -80,3 +84,10 @@ export { getChecksumAddress } from './src/core/get-checksum-address.js';
  * @since 0.1.1
  */
 export * as IPFS from './src/ipfs.js';
+
+/**
+ * This module provides high-level utility functions for working with the Knowledge Graph API.
+ *
+ * @since 0.5.0
+ */
+export * as Graph from './src/graph/index.js';

package.json

@@ -7,9 +7,7 @@
   "main": "./dist/index.js",
   "ascMain": "./dist/index.js",
   "type": "module",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "exports": {
     "./package.json": "./package.json",
     ".": "./dist/index.js",
@@ -47,6 +45,5 @@
     "@bufbuild/buf": "^1.31.0",
     "@bufbuild/protoc-gen-es": "^1.9.0",
     "typescript": "^5.4.5"
-  },
-  "packageManager": "[email protected]"
+  }
 }

src/graph/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_API_HOST = 'https://api-testnet.grc-20.thegraph.com';

src/graph/create-entity.ts

@@ -0,0 +1,60 @@
+import { TYPES_ATTRIBUTE } from '../core/ids/system.js';
+import { generate } from '../id.js';
+import { Relation } from '../relation.js';
+import { Triple } from '../triple.js';
+import type { CreateRelationOp, Op, SetTripleOp, ValueType } from '../types.js';
+
+type Params = {
+  attributes?: {
+    [filedName: string]: string;
+  };
+  mapping?: {
+    [filedName: string]: { id: string; type: ValueType };
+  };
+  types?: Array<string>;
+  relations?: Array<{
+    relationTypeId: string;
+    toId: string;
+  }>;
+};
+
+export const createEntity = async ({ attributes, mapping, types, relations }: Params) => {
+  const id = generate();
+  const ops: Array<Op> = [];
+  if (attributes && mapping) {
+    for (const [fieldName, value] of Object.entries(attributes)) {
+      const attributeMapping = mapping[fieldName];
+      if (!attributeMapping) {
+        throw new Error(`Attribute ID for field ${fieldName} not found`);
+      }
+      const setTripleOp: SetTripleOp = Triple.make({
+        entityId: id,
+        attributeId: attributeMapping.id,
+        value: {
+          type: attributeMapping.type,
+          value,
+        },
+      });
+
+      ops.push(setTripleOp);
+    }
+  }
+
+  if (types) {
+    // add types
+    for (const typeId of types) {
+      const setRelationOp: CreateRelationOp = Relation.make({
+        fromId: id,
+        relationTypeId: TYPES_ATTRIBUTE,
+        toId: typeId,
+      });
+      ops.push(setRelationOp);
+    }
+  }
+
+  if (relations) {
+    // TODO add relations
+  }
+
+  return { id, ops };
+};

src/graph/create-relation-type.ts

@@ -0,0 +1,44 @@
+import { ATTRIBUTE, NAME_ATTRIBUTE, SCHEMA_TYPE, TYPES_ATTRIBUTE } from '../core/ids/system.js';
+import { generate } from '../id.js';
+import { Relation } from '../relation.js';
+import { Triple } from '../triple.js';
+import type { CreateRelationOp, Op, SetTripleOp } from '../types.js';
+
+type Params = {
+  from: string;
+  to: string;
+  name: string;
+};
+
+export const createRelationType = async ({ from, to, name }: Params) => {
+  const id = generate();
+  const ops: Op[] = [];
+
+  const nameTripleOp: SetTripleOp = Triple.make({
+    entityId: id,
+    attributeId: NAME_ATTRIBUTE,
+    value: {
+      type: 'TEXT',
+      value: name,
+    },
+  });
+  ops.push(nameTripleOp);
+
+  const setRelationOp: CreateRelationOp = Relation.make({
+    fromId: id,
+    relationTypeId: TYPES_ATTRIBUTE,
+    toId: SCHEMA_TYPE, // this sets the relation type to be a typ type
+  });
+  ops.push(setRelationOp);
+
+  const setRelationOp2: CreateRelationOp = Relation.make({
+    fromId: id,
+    relationTypeId: TYPES_ATTRIBUTE,
+    toId: ATTRIBUTE, // this sets the relation type to be an "property" type
+  });
+  ops.push(setRelationOp2);
+
+  // TODO relations
+
+  return { id, ops };
+};

src/graph/create-relation.ts

@@ -0,0 +1,26 @@
+import { DEFAULT_API_HOST } from './constants.js';
+
+type Params = {
+  editorAddress: string;
+  name: string;
+  options?: {
+    apiHost?: string;
+  };
+};
+
+export const createSpace = async (params: Params) => {
+  const apiHost = params.options?.apiHost || DEFAULT_API_HOST;
+  const result = await fetch(`${apiHost}/deploy`, {
+    method: 'POST',
+    body: JSON.stringify({
+      spaceName: params.name,
+      initialEditorAddress: params.editorAddress,
+    }),
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  });
+
+  const { spaceId } = await result.json();
+  return { id: spaceId };
+};

src/graph/create-space.ts

@@ -0,0 +1,48 @@
+import { SCHEMA_TYPE, TYPES_ATTRIBUTE } from '../core/ids/system.js';
+import { generate } from '../id.js';
+import { Relation } from '../relation.js';
+import { Triple } from '../triple.js';
+import type { CreateRelationOp, Op, SetTripleOp, ValueType } from '../types.js';
+
+type Params = {
+  attributes: {
+    [filedName: string]: { id?: string; type: ValueType; name: string };
+  };
+  relations?: Array<{
+    relationTypeId: string;
+    toId: string;
+  }>;
+};
+
+export const createType = async ({ attributes }: Params) => {
+  const id = generate();
+  const ops: Op[] = [];
+  const mapping: Record<string, { id: string; type: ValueType }> = {};
+
+  for (const [fieldName, item] of Object.entries(attributes)) {
+    const attributeId = item.id || generate();
+    const setTripleOp: SetTripleOp = Triple.make({
+      entityId: id,
+      attributeId,
+      value: {
+        type: item.type,
+        value: fieldName,
+      },
+    });
+
+    ops.push(setTripleOp);
+    mapping[fieldName] = { id: attributeId, type: item.type };
+  }
+
+  // add the type relation
+  const setRelationOp: CreateRelationOp = Relation.make({
+    fromId: id,
+    relationTypeId: TYPES_ATTRIBUTE,
+    toId: SCHEMA_TYPE,
+  });
+  ops.push(setRelationOp);
+
+  // TODO relations
+
+  return { id, ops, mapping };
+};

src/graph/create-type.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { NAME_ATTRIBUTE } from '../core/ids/system.js';
+import type { Op } from '../types.js';
+import { createEntity } from './create-entity.js';
+import { createRelationType } from './create-relation-type.js';
+import { createType } from './create-type.js';
+
+describe('Graph', () => {
+  it('creates multiple types, relation types, entities, relations', async () => {
+    const operations: Array<Op> = [];
+
+    // create person type
+    const {
+      id: personTypeId,
+      ops: createPersonTypeOps,
+      mapping: personMapping,
+    } = await createType({
+      attributes: {
+        name: {
+          id: NAME_ATTRIBUTE,
+          type: 'TEXT',
+          name: 'Name',
+        },
+        age: {
+          // ID is optional and will be generated automatically
+          type: 'NUMBER',
+          name: 'Age',
+        },
+      },
+    });
+    operations.push(...createPersonTypeOps);
+
+    // create restaurant type
+    const {
+      id: restaurantTypeId,
+      ops: createRestaurantTypeOps,
+      mapping: restaurantMapping,
+    } = await createType({
+      attributes: {
+        name: {
+          id: NAME_ATTRIBUTE,
+          type: 'TEXT',
+          name: 'Name',
+        },
+      },
+    });
+    operations.push(...createRestaurantTypeOps);
+
+    // create loves relation type
+    const { id: relationTypeId, ops: createRelationTypeOps } = await createRelationType({
+      from: personTypeId,
+      to: restaurantTypeId,
+      name: 'Loves',
+    });
+    operations.push(...createRelationTypeOps);
+
+    // create restaurant entity
+    const { id: restaurantId, ops: createRestaurantOps } = await createEntity({
+      types: [restaurantTypeId],
+      attributes: {
+        name: 'Yummy Dining',
+      },
+      mapping: restaurantMapping,
+    });
+    operations.push(...createRestaurantOps);
+
+    // create person entity
+    const { id: personId, ops: createPersonOps } = await createEntity({
+      types: [personTypeId],
+      attributes: {
+        name: 'John Doe',
+      },
+      mapping: personMapping,
+      relations: [{ relationTypeId, toId: restaurantId }],
+    });
+    operations.push(...createPersonOps);
+
+    expect(operations.length).toBe(12);
+
+    // publish all changes
+    // const { proposalId } = await publish({
+    //   operations,
+    //   editName: 'Create person, restaurant, and loves relation',
+    //   spaceId: '0x1',
+    //   accountId: '0x2',
+    // });
+  });
+});

src/graph/graph.test.ts

@@ -0,0 +1,2 @@
+export * from './create-entity.js';
+export * from './create-space.js';