@openfn/language-mysql 2.0.8 → 2.1.0

package/ast.json

@@ -11,7 +11,8 @@
         "tags": [
           {
             "title": "example",
-            "description": "execute(\n  insert('table', fields(\n     field('name', dataValue('name'))\n  ))\n)(state)"
+            "description": "insert(\"users\", { name: (state) => state.data.name });",
+            "caption": "Insert a record into the `users` table"
           },
           {
             "title": "function",
@@ -64,7 +65,8 @@
         "tags": [
           {
             "title": "example",
-            "description": "execute(\n  upsert('table', fields(\n     field('name', dataValue('name'))\n  ))\n)(state)"
+            "description": "upsert(\"table\", { name: (state) => state.data.name });",
+            "caption": "Upsert a record"
           },
           {
             "title": "function",
@@ -122,7 +124,8 @@
           },
           {
             "title": "example",
-            "description": "upsertMany(\n  'users', // the DB table\n  [\n    { name: 'one', email: 'one@openfn.org' },\n    { name: 'two', email: 'two@openfn.org' },\n  ]\n)"
+            "description": "upsertMany(\n  'users', // the DB table\n  [\n    { name: 'one', email: 'one@openfn.org' },\n    { name: 'two', email: 'two@openfn.org' },\n  ]\n)",
+            "caption": "Upsert multiple records"
           },
           {
             "title": "function",
@@ -174,7 +177,8 @@
         "tags": [
           {
             "title": "example",
-            "description": "execute(\n  query({ sql: 'select * from users;' })\n)(state)"
+            "description": "query({ sql: 'select * from users;' })",
+            "caption": "Execute a SQL statement"
           },
           {
             "title": "function",
@@ -217,7 +221,8 @@
         "tags": [
           {
             "title": "example",
-            "description": "execute(\n  sqlString(state => \"select * from items;\")\n)(state)"
+            "description": "sqlString(state => \"select * from items;\")",
+            "caption": "Execute a SQL statement"
           },
           {
             "title": "function",
@@ -834,6 +839,92 @@
         ]
       },
       "valid": true
+    },
+    {
+      "name": "cursor",
+      "params": [
+        "value",
+        "options"
+      ],
+      "docs": {
+        "description": "Sets a cursor property on state.\nSupports natural language dates like `now`, `today`, `yesterday`, `n hours ago`, `n days ago`, and `start`,\nwhich will be converted relative to the environment (ie, the Lightning or CLI locale). Custom timezones\nare not yet supported.\nYou can provide a formatter to customise the final cursor value, which is useful for normalising\ndifferent inputs. The custom formatter runs after natural language date conversion.\nSee the usage guide at {@link https://docs.openfn.org/documentation/jobs/job-writing-guide#using-cursors}",
+        "tags": [
+          {
+            "title": "public",
+            "description": null,
+            "type": null
+          },
+          {
+            "title": "function",
+            "description": null,
+            "name": null
+          },
+          {
+            "title": "example",
+            "description": "cursor($.cursor, { defaultValue: 'today' })",
+            "caption": "Use a cursor from state if present, or else use the default value"
+          },
+          {
+            "title": "example",
+            "description": "cursor(22)",
+            "caption": "Use a pagination cursor"
+          },
+          {
+            "title": "param",
+            "description": "the cursor value. Usually an ISO date, natural language date, or page number",
+            "type": {
+              "type": "NameExpression",
+              "name": "any"
+            },
+            "name": "value"
+          },
+          {
+            "title": "param",
+            "description": "options to control the cursor.",
+            "type": {
+              "type": "NameExpression",
+              "name": "object"
+            },
+            "name": "options"
+          },
+          {
+            "title": "param",
+            "description": "set the cursor key. Will persist through the whole run.",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "options.key"
+          },
+          {
+            "title": "param",
+            "description": "the value to use if value is falsy",
+            "type": {
+              "type": "NameExpression",
+              "name": "any"
+            },
+            "name": "options.defaultValue"
+          },
+          {
+            "title": "param",
+            "description": "custom formatter for the final cursor value",
+            "type": {
+              "type": "NameExpression",
+              "name": "Function"
+            },
+            "name": "options.format"
+          },
+          {
+            "title": "returns",
+            "description": null,
+            "type": {
+              "type": "NameExpression",
+              "name": "Operation"
+            }
+          }
+        ]
+      },
+      "valid": false
     }
   ]
 }

package/dist/index.cjs

@@ -28,8 +28,10 @@ __export(src_exports, {
   alterState: () => import_language_common2.alterState,
   arrayToString: () => import_language_common2.arrayToString,
   combine: () => import_language_common2.combine,
+  cursor: () => import_language_common2.cursor,
   dataPath: () => import_language_common2.dataPath,
   dataValue: () => import_language_common2.dataValue,
+  dateFns: () => import_language_common2.dateFns,
   default: () => src_default,
   each: () => import_language_common2.each,
   execute: () => execute,
@@ -55,8 +57,10 @@ __export(Adaptor_exports, {
   alterState: () => import_language_common2.alterState,
   arrayToString: () => import_language_common2.arrayToString,
   combine: () => import_language_common2.combine,
+  cursor: () => import_language_common2.cursor,
   dataPath: () => import_language_common2.dataPath,
   dataValue: () => import_language_common2.dataValue,
+  dateFns: () => import_language_common2.dateFns,
   each: () => import_language_common2.each,
   execute: () => execute,
   field: () => import_language_common2.field,
@@ -253,8 +257,10 @@ var src_default = Adaptor_exports;
   alterState,
   arrayToString,
   combine,
+  cursor,
   dataPath,
   dataValue,
+  dateFns,
   each,
   execute,
   field,

package/dist/index.js

@@ -10,8 +10,10 @@ __export(Adaptor_exports, {
   alterState: () => alterState,
   arrayToString: () => arrayToString,
   combine: () => combine,
+  cursor: () => cursor,
   dataPath: () => dataPath,
   dataValue: () => dataValue,
+  dateFns: () => dateFns,
   each: () => each,
   execute: () => execute,
   field: () => field,
@@ -35,20 +37,22 @@ import {
 import mysql from "mysql";
 import squel from "squel";
 import {
-  field,
-  fields,
-  sourceValue,
-  alterState,
   fn,
   fnIf,
-  arrayToString,
   each,
-  combine,
+  http,
   merge,
+  field,
+  fields,
+  cursor,
+  dateFns,
+  combine,
   dataPath,
   dataValue,
-  lastReferenceValue,
-  http
+  alterState,
+  sourceValue,
+  arrayToString,
+  lastReferenceValue
 } from "@openfn/language-common";
 function execute(...operations) {
   const initialState = {
@@ -225,8 +229,10 @@ export {
   alterState,
   arrayToString,
   combine,
+  cursor,
   dataPath,
   dataValue,
+  dateFns,
   src_default as default,
   each,
   execute,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/language-mysql",
-  "version": "2.0.8",
+  "version": "2.1.0",
   "description": "A MySQL Language Pack for OpenFn",
   "homepage": "https://docs.openfn.org",
   "main": "dist/index.cjs",
@@ -24,7 +24,6 @@
     "@openfn/language-common": "2.3.0"
   },
   "devDependencies": {
-    "@openfn/simple-ast": "^0.4.1",
     "assertion-error": "^1.0.1",
     "chai": "^3.4.0",
     "deep-eql": "^0.1.3",

package/types/Adaptor.d.ts

@@ -1,11 +1,6 @@
 /**
  * Execute a sequence of operations.
  * Wraps `language-common/execute`, and prepends initial state for mysql.
- * @example
- * execute(
- *   create('foo'),
- *   delete('bar')
- * )(state)
  * @private
  * @param {Operations} operations - Operations to be performed.
  * @returns {Operation}
@@ -13,12 +8,8 @@
 export function execute(...operations: Operations): Operation;
 /**
  * Insert a record
- * @example
- * execute(
- *   insert('table', fields(
- *      field('name', dataValue('name'))
- *   ))
- * )(state)
+ * @example <caption>Insert a record into the `users` table</caption>
+ * insert("users", { name: (state) => state.data.name });
  * @function
  * @public
  * @param {string} table - The target table
@@ -28,12 +19,8 @@ export function execute(...operations: Operations): Operation;
 export function insert(table: string, fields: object): Operation;
 /**
  * Insert or Update a record if matched
- * @example
- * execute(
- *   upsert('table', fields(
- *      field('name', dataValue('name'))
- *   ))
- * )(state)
+ * @example <caption>Upsert a record</caption>
+ * upsert("table", { name: (state) => state.data.name });
  * @function
  * @public
  * @param {string} table - The target table
@@ -44,7 +31,7 @@ export function upsert(table: string, fields: object): Operation;
 /**
  * Insert or update multiple records using ON DUPLICATE KEY
  * @public
- * @example
+ * @example <caption>Upsert multiple records</caption>
  * upsertMany(
  *   'users', // the DB table
  *   [
@@ -61,10 +48,8 @@ export function upsert(table: string, fields: object): Operation;
 export function upsertMany(table: string, data: any[]): Operation;
 /**
  * Execute a SQL statement
- * @example
- * execute(
- *   query({ sql: 'select * from users;' })
- * )(state)
+ * @example <caption>Execute a SQL statement</caption>
+ * query({ sql: 'select * from users;' })
  * @function
  * @public
  * @param {object} options - Payload data for the message
@@ -73,14 +58,12 @@ export function upsertMany(table: string, data: any[]): Operation;
 export function query(options: object): Operation;
 /**
  * Execute a SQL statement
- * @example
- * execute(
- *   sqlString(state => "select * from items;")
- * )(state)
+ * @example <caption>Execute a SQL statement</caption>
+ * sqlString(state => "select * from items;")
  * @function
  * @public
  * @param {String} queryString - A query string (or function which takes state and returns a string)
  * @returns {Operation}
  */
 export function sqlString(queryString: string): Operation;
-export { field, fields, sourceValue, alterState, fn, fnIf, arrayToString, each, combine, merge, dataPath, dataValue, lastReferenceValue, http } from "@openfn/language-common";
+export { fn, fnIf, each, http, merge, field, fields, cursor, dateFns, combine, dataPath, dataValue, alterState, sourceValue, arrayToString, lastReferenceValue } from "@openfn/language-common";