monetdb 1.3.4 → 2.0.1

package/docs/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "docs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "next.config.js",
+  "scripts": {
+    "start": "next dev",
+    "build": "next build"
+  },
+  "keywords": [],
+  "author": {
+    "name": "Svetlin Stalinov",
+    "email": "svetlin.stalinov@monetdbsolutions.com"
+  },
+  "dependencies": {
+    "next": "^14.0.1",
+    "nextra": "^2.13.2",
+    "nextra-theme-docs": "^2.13.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/docs/pages/_app.js

@@ -0,0 +1,9 @@
+import 'nextra-theme-docs/style.css'
+
+export default function Nextra({ Component, pageProps }) {
+  return (
+    <>
+      <Component {...pageProps} />
+    </>
+  )
+}

package/docs/pages/_meta.json

@@ -0,0 +1,18 @@
+{
+  "index": "Getting Started",
+  "filetransfer": "File Transfer",
+  "result": "Query result",
+  "prepstmt": "Prepare Statement",
+  "apis": "API",
+  "versions": {
+      "title": "archive",
+      "type": "menu",
+      "items": {
+          "v0": {
+              "title": "v0",
+              "href": "https://github.com/MonetDB/monetdb-nodejs/blob/master/docs/v0"},
+          "v1": {
+              "title": "v1",
+              "href": "https://github.com/MonetDB/monetdb-nodejs/blob/master/docs/v1"}}
+  }
+}

package/docs/pages/apis/_meta.json

@@ -0,0 +1,4 @@
+{
+    "connection": "Connecting",
+    "result": "QueryResult"
+}

package/docs/pages/apis/connection.mdx

@@ -0,0 +1,60 @@
+## Connecting
+```ts
+const conn = new Connection(config: MapiConfig | string);
+```
+, all the optional fields get default values if not specified.
+### Using configuration options
+```ts
+interface MapiConfig {
+    database: string;
+    username?: string;
+    password?: string;
+    language?: MAPI_LANGUAGE; // sql
+    host?: string;
+    port?: number;
+    timeout?: number;
+    autoCommit?: boolean;
+    replySize?: number;
+}
+
+const defaults = {
+    host: process.env.MAPI_HOST || 'localhost',
+    port: process.env.MAPI_PORT || 50000,
+    username: process.env.MAPI_USER || 'monetdb',
+    password: process.env.MAPI_PASSWORD || 'monetdb',
+    database: process.env.MAPI_DATABASE,
+    autoCommit: false,
+    replySize: -1,
+};
+
+const config: MapiConfig = {
+    ...defaults
+    database: 'test',
+    }
+const conn = new Connection(config);
+```
+### Using URL
+```ts
+const conn = new Connection('mapi:monetdb://<username>:<password>@<hostname>:<port>/<database>');
+```
+### Connection object
+```ts
+declare class Connection extends EventEmitter {
+    autoCommit?: boolean;
+    replySize?: number;
+    sizeHeader?: boolean;
+    mapi: MapiConnection;
+    constructor(params: MapiConfig | MAPI_URI);
+    connect(callback?: ConnectCallback): Promise<boolean>;
+    close(): Promise<boolean>;
+    commit(): Promise<any>;
+    private command;
+    execute(sql: string, stream?: boolean): Promise<QueryResult|QueryStream>;
+    prepare(sql: string): Promise<PrepareStatement>;
+    setAutocommit(v: boolean): Promise<boolean>;
+    setReplySize(v: number): Promise<number>;
+    setSizeHeader(v: boolean): Promise<boolean>;
+    setTimezone(sec: number): Promise<any>;
+    rollback(): Promise<any>;
+}
+```

package/docs/pages/apis/result.mdx

@@ -0,0 +1,39 @@
+## Query Result
+The result object returned from sucessful query execution.
+```ts
+type QueryResult = {
+    id?: number;
+    type?: string;
+    queryId?: number;
+    rowCnt?: number;
+    affectedRows?: number;
+    columnCnt?: number;
+    queryTime?: number;
+    sqlOptimizerTime?: number;
+    malOptimizerTime?: number;
+    columns?: Column[];
+    headers?: ResponseHeaders;
+    data?: any[];
+};
+import { Connection } from 'monetdb';
+const conn = new Connection({database: 'test'});
+const ready = await conn.connect();
+const res: QueryResult = await conn.execute('select 1 as one, 2 as two');
+console.log(res);
+// {
+//   type: '&1',
+//   id: 1,
+//   rowCnt: 1,
+//   columnCnt: 2,
+//   queryId: 37,
+//   queryTime: 311,
+//   malOptimizerTime: 129,
+//   sqlOptimizerTime: 22,
+//   columns: [
+//     { table: '.', name: 'one', type: 'tinyint', index: 0 },
+//     { table: '.', name: 'two', type: 'tinyint', index: 1 }
+//   ],
+//   data: [ [ 1, 2 ] ]
+// }
+
+```

package/docs/pages/filetransfer.mdx

@@ -0,0 +1,43 @@
+## File Transfer
+MonetDB supports the non-standard `COPY INTO` statement to load a CSV-like
+text file into a table or to dump a table into a text file. This statement has an
+optional modifier `ON CLIENT` to indicate that the server should not
+try to open the file on the server side but instead ask the client to open it
+on its behalf.
+
+For example::
+```sql
+	COPY INTO mytable FROM 'data.csv' ON CLIENT
+	USING DELIMITERS ',', E'\n', '"';
+```
+For security reason `monetdb-nodejs` enforces files to be realtive to the current
+working directory of the Node.js process.
+## Skip rows and early cancellation
+MonetDB's `COPY INTO` statement allows you to skip, for example, the first
+line in a file using the modifier `OFFSET 2`, and load `n` records from the file using
+`RECORDS` modifier.
+```sql
+	COPY 100 RECORDS OFFSET 2 INTO mytable FROM 'data.csv' ON CLIENT
+```
+, for detailed documentation on `COPY INTO` statement please vist [MonetDB documentation](https://www.monetdb.org/documentation-Jun2023/user-guide/sql-manual/data-loading/)
+## Example
+Assume `data.csv` with the following content
+```bash
+cat<<EOF>data.csv
+1|one
+2|two
+3|three
+EOF
+```
+, then load that into MonetDB
+```ts
+import {Connection} from 'monetdb';
+
+const conn = new Connection({database: 'test'});
+const ready = await conn.connect();
+await conn.execute('create table foo(i int, a varchar(10))');
+let res = await conn.execute(`copy into foo from \'data.csv\' on client`);
+res = await conn.execute('select * from foo order by i');
+console.log(res.data);
+// [[1, 'one'], [2, 'two'], [3, 'three']]
+```

package/docs/pages/index.mdx

@@ -0,0 +1,27 @@
+---
+title: Getting Started
+slug: /
+---
+
+## Installation
+
+```bash
+$ npm install monetdb
+```
+
+## Usage
+The simplest way to connect is to use default connection options and pass only the database name.
+
+```js
+import { Connection} from 'monetdb'
+
+const opt = {database: 'test'}
+
+const conn = new Connection(opt)
+const ready = await conn.connect();
+const res = conn.exec('select 42');
+console.log(res.data)
+await conn.close();
+```
+, see [connection api](/apis/connection) for more details.
+

package/docs/pages/prepstmt.mdx

@@ -0,0 +1,13 @@
+## Prepare Statement
+The PREPARE statement compiles an SQL statement into its execution plan on the server. This is useful for statements which need to be executed many times but with different values each time, such as an INSERT or UPDATE or SELECT query.
+```ts
+const ready = await conn.connect();
+let res = await conn.execute('create table foo(a int, b boolean, c string, d date, f decimal)');
+const prepStmt = await conn.prepare('insert into foo values (?, ?, ?, ?, ?)');
+res = await prepStmt.execute(1, true, 'first', '2022-12-12', 1.11);
+res = await prepStmt.execute(2, false, 'second', '2022-12-12', 2.22);
+res = await prepStmt.execute(3, true, 'third', '2022-12-12', 3.33);
+await prepStmt.release();
+```
+For more information on prepare statement please visit [MonetDB documentation](https://www.monetdb.org/documentation-Jun2023/user-guide/sql-manual/data-manipulation/prepare-statement/). 
+

package/docs/pages/result.mdx

@@ -0,0 +1,41 @@
+## Query result size
+Query result size can be set with `replySize` `Connection` option. It defines the number of data rows returned in the initial response.
+By default this options is set to `-1`, which means fetch all the data. If `replySize` is set to any positive number, only that many
+data rows will be fetched, while the rest will stay cached at the server. The `replySize` can be set initially when connection is created, or by invoking `setReplySize` method on the `Connection` object.
+```ts
+// set replySize to 100
+const conn = new Connection({database: 'test', replySize: 100});
+await conn.connect();
+let res = await conn.execute("select * from generate_series(1, 1001)");
+console.log(res.data.length);
+// 100
+await conn.setReplySize(-1); // back to default
+res = await conn.execute("select * from generate_series(1, 1001)");
+console.log(res.data.length);
+// 1000
+```
+## Streaming query result
+When query result is quite large it's often useful to start process the data chunks as soon as they are available
+on the client. This can be achieved by invoking `execute` method on the `Connection` object with `stream=true`.
+```ts
+//  execute(sql: string, stream?: boolean): Promise<any>;
+const ready = await conn.connect();
+const stream: QueryStream = await conn.execute('select * from generate_series(1, 10000)', true);
+const colInfo = [];
+const data = [];
+stream.on('header', (cols: any[]) => {
+    // do something with col info
+});
+
+stream.on('data', (tuples: any[]) => {
+    for (let t of tuples) {
+        data.push(t);
+    }
+});
+
+stream.on('end', () => {
+  // do something on end of streaming
+});
+
+await conn.close();
+```

package/docs/theme.config.js

@@ -0,0 +1,35 @@
+// theme.config.js
+export default {
+  project: {
+    link: 'https://github.com/MonetDB/monetdb-nodejs',
+  },
+  docsRepositoryBase: 'https://github.com/MonetDB/monetdb-nodejs/blob/master/docs', // base URL for the docs repository
+  darkMode: true,
+  footer: true,
+  navigation: {
+    prev: true,
+    next: true,
+  },
+  footer: {
+    text: `Mozilla Public License, v.2.0 ${new Date().getFullYear()}`,
+  },
+  editLink: {
+    text: 'Edit this page on GitHub',
+  },
+  logo: (
+    <>
+      <span>monetdb-nodejs</span>
+    </>
+  ),
+  head: (
+    <>
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <meta
+        name="description"
+        content="MonetDB Node.js connector"
+      />
+      <meta name="og:title" content="monetdb-nodejs" />
+      <meta name="og:description" content="MonetDB Node.js driver" />
+    </>
+  ),
+}