The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
(ns metabase-enterprise.data-apps.generate.schema.javascript
"A small TypeScript AST encoded as tagged vectors, and a printer for it.
The AST covers exactly the subset of TypeScript that generated schema modules
emit. Expressions:
[:lit 42] ; any JSON-encodable literal
[:ref \"tables\" \"orders\" :fields] ; property path => tables.orders.fields
[:call \"pickFields\" expr ...] ; call expression, args printed inline
[:arr expr-or-item ...] ; array literal
[:obj entry ...] ; object literal
Object entries are `[key expr]` or `[key {:metadata {...}} obj]`; array
items are bare expressions or `[:item {:metadata {...}} obj]`, where `obj`
is an `[:obj ...]`. Metadata is a JSON-encodable map, printed as a
`/* metadata: {...} */` block first inside the entry's object, before its
properties, so a reader meets it before the data it describes and it never
reaches runtime code. Statements:
[:const \"tables\" expr] ; const tables = <expr> as const;
[:raw \"function helper() {...}\"] ; verbatim TypeScript
[:export \"tables\"] ; export { tables };
[:module statement ...] ; one printed file
For example:
[:module
[:const \"tables\"
[:obj [\"orders\" {:metadata {\"entityId\" \"abc123\"}}
[:obj [\"type\" [:lit \"table\"]]
[\"ids\" [:arr [:lit 1] [:lit 2]]]]]]]
[:export \"tables\"]]
prints as:
const tables = {
orders: {
/* metadata: { \"entityId\": \"abc123\" } */
type: \"table\",
ids: [ 1, 2 ]
}
} as const;
export { tables };
Rendering rules: arrays whose items are all literals print on one line;
`:call` arguments always print inline; object keys print bare when they are
valid JavaScript identifiers and quoted otherwise. A metadata block prints on
one line, nested arrays and objects included, so an entry's metadata is the
line before its properties and a reader can find it with `grep`. [[render-js]]
prints a `:module`; [[Module]] is the Malli schema for the whole grammar.
The printer is deliberately option-free and policy-free: decisions about
*what* to emit (runtime keys, metadata, compaction) belong in
`metabase-enterprise.data-apps.generate.schema.render`, which builds this AST. If the output needs
new syntax, add a node type and its printer here rather than concatenating
TypeScript strings elsewhere."
(:require
[clojure.string :as str]
[metabase.util :as u]
[metabase.util.json :as json]))
(set! *warn-on-reflection* true)
(def ^:private expression-tags
#{:lit :ref :call :arr :obj})
(def ^:private key-schema
[:or :string :keyword])
(def Module
"Malli schema for the TypeScript AST accepted by [[render-js]]."
[:schema {:registry
{::entry-options [:map {:closed true}
[:metadata {:optional true} [:map-of key-schema :any]]]
;; Metadata prints as a block inside the entry's object, so only an object can carry it.
::entry [:or
[:tuple key-schema [:ref ::expr]]
[:tuple key-schema [:ref ::entry-options] [:ref ::obj]]]
::item [:tuple [:= :item] [:ref ::entry-options] [:ref ::obj]]
::obj [:cat [:= :obj] [:* [:schema [:ref ::entry]]]]
::expr [:multi {:dispatch first}
[:lit [:tuple [:= :lit] :any]]
[:ref [:cat [:= :ref] [:+ key-schema]]]
[:call [:cat [:= :call] :string [:* [:schema [:ref ::expr]]]]]
[:arr [:cat [:= :arr] [:* [:or
[:schema [:ref ::item]]
[:schema [:ref ::expr]]]]]]
[:obj [:ref ::obj]]]
::statement [:multi {:dispatch first}
[:const [:tuple [:= :const] key-schema [:ref ::expr]]]
[:raw [:tuple [:= :raw] :string]]
[:export [:tuple [:= :export] key-schema]]]}}
[:cat [:= :module] [:* [:schema [:ref ::statement]]]]])
(defn expression?
"Returns true when `value` is an AST expression node."
[value]
(and (vector? value)
(contains? expression-tags (first value))))
(defn call?
"Returns true when `value` is a `[:call ...]` expression node."
[value]
(and (vector? value)
(= :call (first value))))
(def ^:private js-identifier-pattern
#"[A-Za-z_$][A-Za-z0-9_$]*")
(defn- spaces
[indent]
(apply str (repeat indent " ")))
(defn- javascript-key
"Renders a value as a JavaScript object key.
Valid identifiers render bare e.g. orders; everything else renders as a quoted
property name e.g. \"orders-by-month\"."
[entry-key]
(let [key-name (u/qualified-name entry-key)]
(if (re-matches js-identifier-pattern key-name)
key-name
(json/encode key-name))))
(defn- reference-path
"Renders `[:ref ...]` segments as a JavaScript property path."
[path-segments]
(str (u/qualified-name (first path-segments))
(apply str (for [path-segment (rest path-segments)]
(let [segment-name (u/qualified-name path-segment)]
(if (re-matches js-identifier-pattern segment-name)
(str "." segment-name)
(str "[" (json/encode segment-name) "]")))))))
(defn- entry-parts
"Returns `[key entry-options expr]` for either entry form."
[entry]
(if (= 3 (count entry))
entry
[(first entry) nil (second entry)]))
(defn- item-parts
"Returns `[entry-options expr]` for either array item form."
[item]
(if (and (vector? item) (= :item (first item)))
[(second item) (nth item 2)]
[nil item]))
(defn- metadata-json
"Renders `value` as JSON on one line, nested arrays and objects included."
[value]
(cond
(map? value) (str "{ "
(str/join ", " (for [[k v] value]
(str (json/encode (u/qualified-name k)) ": " (metadata-json v))))
" }")
(sequential? value) (str "[ " (str/join ", " (map metadata-json value)) " ]")
:else (json/encode value)))
(defn- metadata-block
"Returns a `/* metadata: {...} */` block. A `*/` can only occur inside a JSON string, where it is written as the
equivalent `*\\/`, so the block always ends where it should."
[indent metadata]
(str (spaces indent) "/* metadata: "
(str/replace (metadata-json metadata) "*/" "*\\/")
" */"))
(declare render-expression)
(defn- render-inline
"Renders an expression on a single line, for `:call` arguments."
[node]
(case (first node)
:lit (json/encode (second node))
:ref (reference-path (rest node))
:call (let [[_ function-name & args] node]
(str function-name "(" (str/join ", " (map render-inline args)) ")"))
:arr (str "[ " (str/join ", " (map render-inline (rest node))) " ]")
:obj (str "{ "
(str/join ", " (for [entry (rest node)
:let [[entry-key options expr] (entry-parts entry)]]
(do
;; An inline object has no room for a block, so refuse rather than drop it.
(when (seq (:metadata options))
(throw (ex-info "Metadata can only be attached to an object on its own lines."
{:node node})))
(str (javascript-key entry-key) ": " (render-inline expr)))))
" }")))
(defn- literal-node?
[node]
(and (vector? node) (= :lit (first node))))
(defn- render-object
[entries indent metadata]
(let [inner-indent (+ indent 2)
lines (for [entry entries
:let [[entry-key options expr] (entry-parts entry)]]
(str (spaces inner-indent)
(javascript-key entry-key)
": "
(render-expression expr inner-indent (:metadata options))))
;; the block comes first, so a reader meets it before the properties it describes
body (str/join "\n" (remove str/blank? [(when (seq metadata) (metadata-block inner-indent metadata))
(str/join ",\n" lines)]))]
(if (str/blank? body)
"{ }"
(str "{\n" body "\n" (spaces indent) "}"))))
(defn- render-array
[items indent]
(cond
(empty? items)
"[ ]"
(every? literal-node? items)
(str "[ " (str/join ", " (map #(json/encode (second %)) items)) " ]")
:else
(str "[\n"
(str/join ",\n"
(for [item items
:let [[options expr] (item-parts item)
item-indent (+ indent 2)]]
(str (spaces item-indent)
(render-expression expr item-indent (:metadata options)))))
"\n" (spaces indent) "]")))
(defn- render-expression
"Renders `node` at `indent`. `metadata`, when present, prints inside `node`, which must then be an object."
([node indent]
(render-expression node indent nil))
([node indent metadata]
(when (and (seq metadata) (not= :obj (first node)))
(throw (ex-info "Metadata can only be attached to an object." {:node node})))
(case (first node)
:lit (json/encode (second node))
:ref (reference-path (rest node))
:call (render-inline node)
:obj (render-object (rest node) indent metadata)
:arr (render-array (rest node) indent))))
(defn- render-statement
[statement]
(case (first statement)
:raw (second statement)
:const (let [[_ const-name expr] statement]
(str "const " (u/qualified-name const-name) " = "
(render-expression expr 0) " as const;"))
:export (str "export { " (u/qualified-name (second statement)) " };")))
(defn render-js
"Renders a `[:module ...]` AST as TypeScript source."
[[_ & statements]]
(str (str/join "\n\n" (map render-statement statements)) "\n"))