[Lens] [@kbn/tinymath] Add new defaults function (elastic#142087)

* ✨ Add new defaults function

* ✨ Add new defaults function

* 📝 Rewrite the doc

Co-authored-by: Joe Reuter <[email protected]>

packages/kbn-tinymath/src/functions/defaults.js

@@ -0,0 +1,30 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+/**
+ * Returns the default provided value when the first value if null. If at least one array is passed into the function, the function will be applied index-wise to each element.
+ * @param {(any|any[])} a array of any values
+ * @param {(any)} b a value to use as fallback.
+ * @return {(any|any[])} The `a` value if not null, `b` otherwise. Returns an array where each element is default to `b` when null, or kept the original value if `a` is an array.
+ *
+ * @example
+ * defaults(null, 1) // returns 1
+ * defaults([3, null, 5], 1) // returns [3, 1, 5]
+ * defaults(5, 1) // returns 5
+ */
+
+module.exports = { defaults };
+
+function defaults(a, b) {
+  if (Array.isArray(a)) {
+    return a.map((v) => (v == null ? b : v));
+  }
+  return a == null ? b : a;
+}
+
+defaults.skipNumberValidation = true;

packages/kbn-tinymath/src/functions/index.js

@@ -14,6 +14,7 @@ const { clamp } = require('./clamp');
 const { cos } = require('./cos');
 const { count } = require('./count');
 const { cube } = require('./cube');
+const { defaults } = require('./defaults');
 const { degtorad } = require('./degtorad');
 const { divide } = require('./divide');
 const { exp } = require('./exp');
@@ -56,6 +57,7 @@ module.exports = {
     count,
     cube,
     degtorad,
+    defaults,
     divide,
     exp,
     first,

packages/kbn-tinymath/test/functions/defaults.test.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+const { defaults } = require('../../src/functions/defaults');
+
+describe('Defaults', () => {
+  it('number, number', () => {
+    expect(defaults(10, 2)).toEqual(10);
+  });
+
+  it('null, number', () => {
+    expect(defaults(null, 2)).toEqual(2);
+  });
+
+  it('number, null', () => {
+    expect(defaults(2, null)).toEqual(2);
+  });
+
+  it('array, number', () => {
+    expect(defaults([10, 20, 30, 40], 10)).toEqual([10, 20, 30, 40]);
+  });
+
+  it('arrays with null, number', () => {
+    expect(defaults([null, 20, 30, null], 10)).toEqual([10, 20, 30, 10]);
+  });
+
+  it('empty array, number', () => {
+    expect(defaults([], 10)).toEqual([]);
+  });
+
+  it('skips number validation', () => {
+    expect(defaults).toHaveProperty('skipNumberValidation', true);
+  });
+});

x-pack/plugins/lens/public/indexpattern_datasource/operations/definitions/formula/util.ts

@@ -112,7 +112,6 @@ function getTypeI18n(type: string) {
   return '';
 }
 
-// Todo: i18n everything here
 export const tinymathFunctions: Record<
   string,
   {
@@ -527,6 +526,26 @@ Example: Find the minimum between two fields averages
     `,
     }),
   },
+  defaults: {
+    positionalArguments: [
+      {
+        name: i18n.translate('xpack.lens.formula.value', { defaultMessage: 'value' }),
+        type: getTypeI18n('number'),
+      },
+      {
+        name: i18n.translate('xpack.lens.formula.defaultValue', { defaultMessage: 'default' }),
+        type: getTypeI18n('number'),
+      },
+    ],
+    help: i18n.translate('xpack.lens.formula.defaultFunction.markdown', {
+      defaultMessage: `
+Returns a default numeric value when value is null.
+
+Example: Return -1 when a field has no data
+\`defaults(average(bytes), -1)\`
+    `,
+    }),
+  },
 };
 
 export function isMathNode(node: TinymathAST | string) {