Merge pull request #9 from Linkurious/develop

v1.0.0

.gitignore

@@ -3,4 +3,7 @@ sqlcl/
 **/node_modules/
 **/dist/
 example/compose-stack/transform.mjs
-docs/.vitepress/cache
+example/**/package-lock.json
+docs/.vitepress/cache
+docs/api
+reports

Jenkinsfile

@@ -8,7 +8,8 @@ nodeJob {
   runForwardMerge = false
   createGitTag = true
   runPreReleaseOnUpload = false
-  npmPackPath = './dist'
+  runDependencyVersionCheck = false
+  npmPackPath = '.'
   gitTagPrefix = 'v'
   runBookeeping = true
   runNpmPublish = true

README.md

@@ -13,3 +13,7 @@ Please check our [getting started](https://linkurious.github.io/ogma-oracle-pars
 # How to contribute ?
 
 This is an open source project maintained by Linkurious, if you want to contribute, you can submit a PR and we'll exmine it.
+
+# Licence
+
+Apache 2.0

docs/.vitepress/config.mts

@@ -1,18 +1,58 @@
-import { defineConfig } from 'vitepress';
+import { DefaultTheme, defineConfig } from 'vitepress';
+import fs from 'fs/promises';
 
+// recursively go into input dir and create a vitepress sidebar config
+function createSidebar(dir) {
+  return fs.readdir(dir, { withFileTypes: true })
+    .then(files => {
+      const promises = files.map(file => {
+        if (file.isDirectory()) {
+          return createSidebar(`${dir}/${file.name}`);
+        } else if (file.name.endsWith('.md')) {
+          return {
+            text: file.name.replace('.md', ''),
+            link: `${dir.replace('docs/', '')}/${file.name.replace('.md', '')}`,
+          };
+        }
+      });
+      return Promise.all(promises);
+    })
+    .then(res => {
+      return res.filter(r => r);
+    });
+}
+const classes = await createSidebar('docs/api/classes');
+// const interfaces = await createSidebar('docs/api/interfaces');
+const sidebar: DefaultTheme.Sidebar = {
+  'api/': [
+    {
+      text: 'OgmaOracleParser',
+      link: 'api/classes/OgmaOracleParser'
+    },
+    {
+      text: 'Types',
+      link: 'api/modules'
+    },
+  ],
+};
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: "ogma-oracle-parser",
   description: "Seamless Ogma and Oracle Property Graph integration",
-  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
+  head: [['link', { rel: 'icon', href: '/ogma-oracle-parser/favicon.ico' }]],
+  base: '/ogma-oracle-parser/',
   themeConfig: {
     logo: '/logo-small.svg',
     nav: [
-      { text: 'Home', link: '/' },
+      { text: 'Getting started', link: '/getting-started' },
       { text: 'Example', link: '/example' },
-      { text: 'API', link: '/api' },
+      { text: 'API', link: '/api/classes/OgmaOracleParser' },
 
     ],
+    sidebar,
+    outline: {
+      level: [2, 3]
+    },
     socialLinks: [
       { icon: 'github', link: 'https://github.com/Linkurious/ogma-oracle-graph-db' }
     ]

docs/API.md

@@ -1,27 +0,0 @@
----
-# https://vitepress.dev/reference/default-theme-home-page
-layout: home
-
-hero:
-  name: "ogma-oracle-parser"
-  text: "A package to easily bridge Ogma and Oracle Property Graph with SQL/PGQ"
-  tagline: ""
-  actions:
-    - theme: brand
-      text: Getting started
-      link: /getting-started
-    - theme: alt
-      text: Example
-      link: /example
-    - theme: alt
-      text: API
-      link: /api
-
-features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
----

docs/example.md

@@ -41,16 +41,16 @@ Then:
 
 ```sh
 npm install
-npm run build && npm run start
+npm run start
 ```
 
 You know have an express app that answers to a few routes by querying your SQL database:
 
-- [GET] /nodes/:`type` Returns all nodes of a certain type. Type must match with the labels passed in your `CREATE PROPERTY GRAPH` call.
-- [GET] /edges/:`types` Returns all edges of a certain type.
-- [GET] /node/:`id` Returns the node corresponding to `id`. Id must be of the form: `LABEL-ID`.
-- [GET] /edge/:`id` Returns the edge corresponding to `id`
-- [GET /expand/:`id` Returns all the neighbors of the node refered by `id`.
+- `[GET] /nodes/:type` Returns all nodes of a certain type. Type must match with the labels passed in your `CREATE PROPERTY GRAPH` call.
+- `[GET] /edges/:types` Returns all edges of a certain type.
+- `[GET] /node/:id` Returns the node corresponding to `id`. Id must be of the form: `LABEL-ID`.
+- `[GET] /edge/:id` Returns the edge corresponding to `id`
+- `[GET /expand/:id` Returns all the neighbors of the node refered by `id`.
 
 ## Start the frontend
 

docs/getting-started.md

@@ -38,7 +38,7 @@ BEGIN
 END;
 ```
 
-## Retrieve your nodes/edges from the Databse in NOdeJS
+## Retrieve your nodes/edges from the Databse in NodeJS
 
 First, install the ogma, the oracle connector and ogma-oracle-parser:
 
@@ -153,6 +153,27 @@ Now, what you get is this:
 Where `vlabel` and `elabel` are the labels you have passed to SQL in your `CREATE PROPERTY GRAPH` call. `-id` is the id of your element in the table.
 And that's it ! You now have retrieved nodes and edges in the [Ogma format](https://doc.linkurious.com/ogma/latest/api.html#RawGraph)
 
+The plugin also provides a [getRawGraph](/api/classes/OgmaOracleParser.html#getrawgraph) function that does all the work for you. You can use it like this:
+
+```ts
+import { getRawGraph } from "@linkurious/ogma-oracle-parser";
+...
+
+app.get("/nodes/:type", (req, res) => {
+  const query = `select v
+          from graph_table (
+            openflights_graph
+            match (v1 is ${req.params.type})
+            columns (
+              VERTEX_ID(v1) as v
+            )
+          )`;
+  return getRawGraph(conn, query).then(({ nodes, edges }) => {
+    return { nodes, edges };
+  });
+});
+```
+
 ## Display your nodes in Ogma
 
 Let' s assume you already have a client side project. Just install Ogma:
@@ -177,3 +198,33 @@ axios.get("http://url-to-node-server:port/nodes/VLABEL").then(({ data }) => {
 ```
 
 And you are done !
+
+## Customize your nodes/edges ids
+
+By default, the plugin transforms the `label:{"ID": id}` into `label-id`.
+You can customize this behaviour by creating an instance of the [OgmaOracleParser](/api/classes/OgmaOracleParser.html#constructors) class"
+
+```ts
+import { OgmaOracleParser } from "@linkurious/ogma-oracle-parser";
+
+const { parse, parseLob, getRawGraph } = new OgmaOracleParser({
+  SQLIDtoId: (label, id) => `${label}-${id}`,
+  SQLIDfromId: (id) => {
+    const [label, id] = id.split("-");
+    return `${label}:{"ID": ${id}}`;
+  },
+});
+```
+
+## Node and Edge data types
+
+You can type the data of your nodes and edges by passing [ND](/api/classes/OgmaOracleParser.html#type-parameters) and [ED](/api/classes/OgmaOracleParser.html#type-parameters) value in the `OgmaOracleParser` constructor:
+
+```ts
+type NodeDataType = { name: string; id: number };
+type EdgeDataType = { score: number };
+const { parse, parseLob, getRawGraph } = new OgmaOracleParser<
+  NodeDataType,
+  EdgeDataType
+>();
+```