@01-edu/shared 1.0.2 → 1.0.4

package/attrs.js

@@ -0,0 +1,291 @@
+import { attrs, relationAttrs } from './attrs-defs.js'
+import { languages } from './languages.js'
+import { mapEntries, mapValues } from './toolbox.js'
+
+// ⚡ description placeholder
+
+const typeCheckers = {
+  boolean: b => typeof b === 'boolean',
+  number: n => typeof n === 'number',
+  string: s => typeof s === 'string',
+  object: o => typeof o === 'object' && o !== null,
+  array: Array.isArray,
+}
+
+const typeChecker = (defs, value, object, key) => {
+  const { type, check, options } = defs
+
+  if (value == null) {
+    if (!defs.required) return true
+    // if no value for required attribute, reject
+    throw Error(`missing value for required attribute ${key}`)
+  }
+
+  if (!type) throw Error(`attribute type definition is missing for ${key}`)
+
+  if (value?.type === 'function') {
+    if (defs.functionsByName[value.name]) return true
+    throw Error(`function associated not allowed for ${key}`)
+  }
+
+  // if a check is defined and don't pass, reject
+  check?.(value, object, key)
+
+  if (options) {
+    const opts = typeof options === 'function' ? options(object) : options
+    const isAnOption = opts.includes(value)
+    if (!isAnOption) {
+      throw Error(
+        `invalid option for ${key}: should be included in ${opts.join(', ')}`,
+      )
+    }
+  }
+
+  // basic case
+  if (typeCheckers[type]) {
+    if (!typeCheckers[type](value)) throw Error(`Expect ${type} for ${key}`)
+    return true
+  }
+
+  // complex cases: array
+  if (Array.isArray(type)) {
+    if (!Array.isArray(value)) {
+      throw Error(`invalid attribute value: expects an array for ${key}`)
+    }
+    // every value have to match one of the type definition
+
+    const uniqueDef = type.length === 1 && type[0]
+    const types =
+      !uniqueDef &&
+      Object.fromEntries(type.map(t => [t.type?.type?.value || t.type, t]))
+    for (const [index, v] of value.entries()) {
+      const err = Error('checks failed for all types')
+      err.index = index
+      err.key = key
+      err.label = defs.label
+      const subdefs =
+        uniqueDef || (typeof v === 'object' ? types[v.type] : types[typeof v])
+      if (!subdefs) {
+        err.details = {
+          label: 'Unknown structure',
+          err: Error('no type matches the value'),
+        }
+        throw err
+      }
+      try {
+        typeChecker(subdefs, v, object, key)
+      } catch (error) {
+        err.details = error.details || {
+          label: subdefs.label || error.label,
+          err: error,
+        }
+
+        throw err
+      }
+    }
+
+    // TODO: check "one of" also one day - meaning there is no duplicate
+
+    return true
+  }
+
+  if (typeof type !== 'object') throw Error('invalid attribute type definition')
+
+  if (typeof value !== 'object' || value === null) {
+    throw Error('invalid attribute value: expects an object')
+  }
+
+  // then is necessarily an object. Let's check!
+  const typeEntries = Object.entries(type)
+
+  // check that every key fulfilled is defined in the type definitions
+  const invalidKey = Object.keys(value).find(key => !type[key])
+  if (invalidKey) throw Error(`${invalidKey} is invalid.`)
+
+  for (const [key, defs] of typeEntries) {
+    typeChecker(defs, value[key], object, key)
+  }
+  return true
+}
+
+// same as attrs with the check & function by name generated and descriptions form markdown files
+export const attributes = mapEntries(attrs, ([attrKey, matches]) => [
+  attrKey,
+  mapValues(matches, (defs, type) => ({
+    ...defs,
+    check: (value, object) => typeChecker(defs, value, object, attrKey),
+  })),
+])
+
+export const relationAttributes = mapEntries(
+  relationAttrs,
+  ([attrKey, byParent]) => [
+    attrKey,
+    mapValues(byParent, (matches, parentType) =>
+      mapValues(matches, (defs, childType) => ({
+        ...defs,
+        check: (value, object) => typeChecker(defs, value, object, attrKey),
+      })),
+    ),
+  ],
+)
+
+// map from attrs[name][type] to attrs[type][name]
+export const attrsByType = {}
+
+const languagesEntries = Object.entries(languages)
+for (const [name, matches] of Object.entries(attributes)) {
+  for (const [type, defs] of Object.entries(matches)) {
+    const ofType = attrsByType[type] || (attrsByType[type] = {})
+    ofType[name] = defs
+    // handle translations: generate translation attrs and required status
+    const { label, ...restDefs } = defs
+    if (defs.functionsByName?.translate) {
+      // perf measures done: inscrease from 0.671ms loadtime to 13.261ms
+      // should not impact the perfs
+      for (const [code, language] of languagesEntries) {
+        const newLabel = `${label} - ${language}`
+        ofType[`${name}-${code}`] = {
+          ...restDefs,
+          label: newLabel,
+          lgCode: code,
+          required: false,
+        }
+      }
+    }
+  }
+}
+
+// map from attrs[name][parentType][childType]
+// to attrs[parentType][childType][name]
+export const relationAttrsByParentType = {}
+for (const [name, byParent] of Object.entries(relationAttributes)) {
+  for (const [parentType, byChild] of Object.entries(byParent)) {
+    for (const [childType, defs] of Object.entries(byChild)) {
+      const ofParentType =
+        relationAttrsByParentType[parentType] ||
+        (relationAttrsByParentType[parentType] = {})
+      const ofParentChildType =
+        ofParentType[childType] || (ofParentType[childType] = {})
+      ofParentChildType[name] = defs
+      // for now, there is no relation attr that is translatable
+      // if it is created one day, add handling of translations here
+    }
+  }
+}
+const attrsEntriesByType = mapValues(attrsByType, Object.entries)
+const relAttrsEntriesByParentType = mapValues(
+  relationAttrsByParentType,
+  byParent => mapValues(byParent, Object.entries),
+)
+export const getDefaultAttrsEntries = object =>
+  attrsEntriesByType[object.type] || []
+export const getDefaultRelAttrsEntries = (parentType, childType) =>
+  relAttrsEntriesByParentType[parentType]?.[childType] || []
+
+export const getDefaultAttrs = object => attrsByType[object.type]
+export const getDefaultRelAttrs = (parentType, childType) =>
+  relationAttrsByParentType[parentType]?.[childType]
+
+const findDefaultOrNamedFunction = (value, defs) => {
+  // Should be true only for required impure default value functions
+  if (value === undefined || value === null) return defs.required && defs.value
+  if (value.type !== 'function') return
+  // Otherwise we only care about when the default function was overridden
+  // by another impure function
+
+  return defs.functionsByName?.[value.name]
+}
+
+const applyDefs = (key, value, defs, object, getUser) => {
+  // xp, child.attrs.rewards, defs.type.xp, object
+  // reward, child.attrs, defs, object
+  if (value === undefined || value === null) return
+  const fn = findDefaultOrNamedFunction(value[key], defs)
+  if (typeof fn === 'function') {
+    if (getUser) {
+      Object.defineProperty(value, key, {
+        get: () => fn(object, getUser(), key),
+        enumerable: true,
+      })
+    } else if (fn.name === 'translate') {
+      // if we don't have a user, assume english language
+      value[key] = value[`${key}-en`]
+    }
+  }
+}
+
+const expandAttr = (key, value, defs, object, getUser) => {
+  const isFunction = value[key]?.type === 'function'
+  if (Array.isArray(defs.type) && value[key] && !isFunction) {
+    // handle multiple sub-types defs for array items
+    // there can be different subtypes defs of type object,
+    // as long as they all have a type property (mandatory - to distinguish def to check)
+    // and one subtype def for each primary data type
+    const types =
+      defs.type.length > 1 &&
+      Object.fromEntries(defs.type.map(t => [t.type.type?.value || t.type, t]))
+
+    for (let i = 0; i < value[key].length; i++) {
+      let def
+      if (types) {
+        const isObject = typeof value[key][i] === 'object'
+        const invalidType =
+          !value[key][i].type || typeof value[key][i].type !== 'string'
+        const allowedTypes = Object.keys(types).join(',').slice(0, -1)
+        if (isObject && invalidType) {
+          console.warn(
+            `Type not allowed. Object item for ${key} array (#${i} item) must have one of these "type" property: ${allowedTypes}.`,
+          )
+        }
+        def = isObject ? types[value[key][i].type] : types[typeof value[key][i]]
+        if (!def) {
+          console.warn(
+            `Missing type definition. Object item for ${key} array (#${i} item) must have one of these "type" property: ${allowedTypes}.`,
+          )
+        }
+      }
+
+      expandAttr(i, value[key], def || defs.type[0], object, getUser)
+    }
+  } else if (typeof defs.type === 'object' && value[key] && !isFunction) {
+    for (const [childKey, subDefs] of Object.entries(defs.type)) {
+      expandAttr(childKey, value[key], subDefs, object, getUser)
+    }
+  } else {
+    applyDefs(key, value, defs, object, getUser)
+  }
+}
+
+export const expandAttrs = (object, getUser) => {
+  if (!object.children) return (object.children = {})
+  let prev
+  for (const child of Object.values(object.children)) {
+    child.parent = object
+    prev && (prev.next = child) && (child.prev = prev)
+    prev = child
+
+    // apply missing default functions
+    // a function can only be missing if it require the user,
+    // the event or current time
+    for (const [key, defs] of getDefaultAttrsEntries(child)) {
+      if (child.attrs[key] === null) {
+        console.warn(`value is null for ${child.name} - ${key} - ${child.id}`)
+      }
+      expandAttr(key, child.attrs, defs, child, getUser)
+    }
+    for (const [key, defs] of getDefaultRelAttrsEntries(
+      object.type,
+      child.type,
+    )) {
+      if (child.attrs[key] === null) {
+        console.warn(`value is null for ${child.name} - ${key} - ${child.id}`)
+      }
+      expandAttr(key, child.attrs, defs, child, getUser)
+    }
+
+    expandAttrs(child, getUser)
+  }
+}
+
+export { attrs, relationAttrs }

package/definitions-checker.js

@@ -0,0 +1,236 @@
+import { childTypes, objectTypes } from './toolbox.js'
+import { attributes, relationAttributes } from './attrs.js'
+
+const normalize = str =>
+  str
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replaceAll(' ', '-')
+
+const assertDef = def => {
+  const {
+    type,
+    name,
+    attrs,
+    children,
+    childrenAttrs,
+    refId,
+    referencePath,
+    ...rest
+  } = def
+  const [extra] = Object.keys(rest)
+  if (extra) {
+    throw Error(
+      `Unexpected property ${extra}, did you mean to define an attribute ?`,
+    )
+  }
+  if (!objectTypes.has(type)) throw Error(`Invalid type property`)
+  if (!name || typeof name !== 'string') throw Error(`Invalid name property`)
+  if (attrs && typeof attrs !== 'object') throw Error(`Invalid attrs property`)
+  if (refId && typeof refId !== 'number') throw Error(`Invalid refId property`)
+  if (childrenAttrs) throw Error(`childrenAttrs is no longer supported`)
+
+  for (const [key, value] of Object.entries(attrs)) {
+    if (relationAttributes[key]) {
+      throw Error(
+        `Attr ${key} should be defined in the relation with its parent, not on the object itself.`,
+      )
+    }
+
+    const matches = attributes[key]
+    if (!matches) throw Error(`Undefined attr ${key}`)
+    const attrDefs = matches[type]
+    if (!attrDefs) {
+      const types = Object.keys(matches).join(', ')
+      throw Error(`${type} does not match any of ${types} for attr ${key}`)
+    }
+
+    if (attrDefs.deprecated) {
+      throw Error(`attr ${key} deprecated: ${attrDefs.deprecated}`)
+    }
+  }
+}
+
+// TODO: maybe check for circularity here
+// I skipped this check for simplicity and performance
+// because since we already have check that we have a correct parent / child type
+// structure, a circular relation should not be possible
+const buildTree = ({ name, type, attrs, children, referencePath }, parent) => {
+  const object = { name, type, attrs, children: {}, referencePath, parent }
+  if (!children) return object
+  let prev
+  for (const [key, { ref, ...rest }] of Object.entries(children)) {
+    const child = buildTree(ref, object)
+    child.attrs = { ...child.attrs, ...rest }
+    prev && (prev.next = child)
+    child.prev = prev
+    object.children[key] = child
+  }
+  return object
+}
+
+const assertRelation = (parent, key, relation) => {
+  if (!/^[a-z0-9-]*$/.test(key)) {
+    throw Error(
+      `Invalid key for child ${key} Kebab-case key suggestion: ${normalize(key)}`,
+    )
+  }
+
+  const child = relation.ref
+  const { type } = child
+  const allowedTypes = childTypes[parent.type]
+  if (!allowedTypes.includes(type)) {
+    throw Error(`Type ${type} ${key} is not a possible child`)
+  }
+
+  // Should never happen
+  if (parent.referencePath === child.referencePath) {
+    throw Error(`Self reference in child ${key}`)
+  }
+
+  for (const [key, value] of Object.entries(relation)) {
+    if (key === 'ref') continue
+    const matches = attributes[key]
+    if (matches?.[type]?.restrictive) {
+      throw Error(
+        `Attr ${key} should be defined on the object itself, not in the relation with its parent.`,
+      )
+    }
+    const relMatches = relationAttributes[key]
+    if (!matches && !relMatches) throw Error(`Undefined attr ${key}`)
+    const attrDefs = (relMatches?.[parent.type] || matches)[type]
+    if (!attrDefs) {
+      const types = Object.keys(matches).join(', ')
+      throw Error(`${type} does not match any of ${types} for attr ${key}`)
+    }
+
+    if (attrDefs.deprecated) {
+      throw Error(`attr ${key} deprecated: ${attrDefs.deprecated}`)
+    }
+  }
+}
+
+const checkAttrs = object => {
+  for (const [key, value] of Object.entries(object.attrs)) {
+    try {
+      const attrDefs =
+        relationAttributes[key]?.[object.parent?.type]?.[object.type] ||
+        attributes[key][object.type]
+
+      if (value?.type === 'function') {
+        const fn = attrDefs.functionsByName?.[value.name]
+        if (!fn) throw Error(`function ${value.name} not found for attr ${key}`)
+      } else if (!attrDefs.check(value, object)) {
+        throw Error(`wrong type for attr ${key}`)
+      }
+    } catch (err) {
+      err.parentRef = object.parent?.referencePath
+      err.childRef = object.referencePath
+      err.value = value
+      err.key = key
+      throw err
+    }
+  }
+
+  for (const child of Object.values(object.children)) {
+    checkAttrs(child)
+  }
+}
+
+// TODO: replace by Set.intersection once available in node
+const intersection = (a, b) => {
+  const result = new Set()
+  for (const element of a) {
+    b.has(element) && result.add(element)
+  }
+  return result
+}
+
+const generatePairs = arr => {
+  const result = []
+  let i = -1
+  // Only go up to the second to last element
+  while (++i < arr.length - 1) {
+    let j = i
+    // Start from the next element to avoid duplicates
+    while (++j < arr.length) {
+      result.push([arr[i], arr[j]])
+    }
+  }
+  return result
+}
+
+const isExam = def => def.type === 'exam'
+const assertExams = definitions => {
+  const groups = {}
+  for (const exam of definitions.filter(isExam)) {
+    let prevExamGroup = 0
+    for (const [key, exercise] of Object.entries(exam.children)) {
+      try {
+        const { group } = exercise
+        if (!group) throw Error('missing exam group')
+
+        const groupDiff = group - prevExamGroup
+        prevExamGroup = group
+        if (groupDiff > 1) throw Error('exam must not have gaps in groups')
+        if (groupDiff < 0) {
+          throw Error('exercise must be sorted by group from lower to greater')
+        }
+
+        // exam exercise group should stay consistent across all exams
+        const prevGroup = groups[key]
+        if (prevGroup == null) {
+          groups[key] = group
+        } else if (prevGroup !== group) {
+          throw Error('Exercise used in different exam groups')
+        }
+      } catch (err) {
+        err.exam = exam.referencePath
+        err.exercise = exercise.ref.referencePath
+        throw err
+      }
+    }
+  }
+}
+
+export const checkAndBuildDefinitions = async readDef => {
+  const cache = {}
+  const getDefs = async ([key, relation]) => {
+    const def = cache[key] || (cache[key] = await readDef(key))
+    try {
+      assertDef(def)
+    } catch (err) {
+      err.type = def.type
+      err.referencePath = def.referencePath
+      throw err
+    }
+    relation && (relation.ref = def)
+    const relations = Object.entries(def.children || {}).map(getDefs)
+    return [def, ...(await Promise.all(relations)).flat()]
+  }
+
+  const definitions = await getDefs([])
+
+  // Assert all relations looks ok, possible child / parent, allowed attributes
+  for (const def of definitions) {
+    if (!def.children) continue
+    const allowedTypes = childTypes[def.type]
+    try {
+      for (const entry of Object.entries(def.children)) {
+        assertRelation(def, entry[0], entry[1])
+      }
+    } catch (err) {
+      err.type = def.type
+      err.referencePath = def.referencePath
+      throw err
+    }
+  }
+
+  // Check all attributes in context
+  const root = buildTree(definitions[0])
+  checkAttrs(root)
+  assertExams(definitions)
+
+  return { definitions, root }
+}

package/languages.js

@@ -0,0 +1,147 @@
+export const languages = {
+  ab: 'Abkhazian',
+  aa: 'Afar',
+  af: 'Afrikaans',
+  sq: 'Albanian',
+  am: 'Amharic',
+  ar: 'Arabic',
+  hy: 'Armenian',
+  as: 'Assamese',
+  ay: 'Aymara',
+  az: 'Azerbaijani',
+  ba: 'Bashkir',
+  eu: 'Basque',
+  bn: 'Bengali (Bangla)',
+  dz: 'Bhutani',
+  bh: 'Bihari',
+  bi: 'Bislama',
+  br: 'Breton',
+  bg: 'Bulgarian',
+  my: 'Burmese',
+  be: 'Byelorussian (Belarusian)',
+  km: 'Cambodian',
+  ca: 'Catalan',
+  zh: 'Chinese (Simplified)',
+  // zh: 'Chinese (Traditional)',
+  co: 'Corsican',
+  hr: 'Croatian',
+  cs: 'Czech',
+  da: 'Danish',
+  nl: 'Dutch',
+  en: 'English',
+  eo: 'Esperanto',
+  et: 'Estonian',
+  fo: 'Faeroese',
+  fa: 'Farsi',
+  fj: 'Fiji',
+  fi: 'Finnish',
+  fr: 'French',
+  fy: 'Frisian',
+  gl: 'Galician',
+  gd: 'Gaelic (Scottish)',
+  gv: 'Gaelic (Manx)',
+  ka: 'Georgian',
+  de: 'German',
+  el: 'Greek',
+  kl: 'Greenlandic',
+  gn: 'Guarani',
+  gu: 'Gujarati',
+  ha: 'Hausa',
+  he: 'Hebrew',
+  hi: 'Hindi',
+  hu: 'Hungarian',
+  is: 'Icelandic',
+  id: 'Indonesian',
+  ia: 'Interlingua',
+  ie: 'Interlingue',
+  iu: 'Inuktitut',
+  ik: 'Inupiak',
+  ga: 'Irish',
+  it: 'Italian',
+  ja: 'Japanese',
+  // jv: 'Javanese',
+  kn: 'Kannada',
+  ks: 'Kashmiri',
+  kk: 'Kazakh',
+  rw: 'Kinyarwanda (Ruanda)',
+  ky: 'Kirghiz',
+  rn: 'Kirundi (Rundi)',
+  ko: 'Korean',
+  ku: 'Kurdish',
+  lo: 'Laothian',
+  la: 'Latin',
+  lv: 'Latvian (Lettish)',
+  li: 'Limburgish ( Limburger)',
+  ln: 'Lingala',
+  lt: 'Lithuanian',
+  mk: 'Macedonian',
+  mg: 'Malagasy',
+  ms: 'Malay',
+  ml: 'Malayalam',
+  mt: 'Maltese',
+  mi: 'Maori',
+  mr: 'Marathi',
+  mo: 'Moldavian',
+  mn: 'Mongolian',
+  na: 'Nauru',
+  ne: 'Nepali',
+  no: 'Norwegian',
+  oc: 'Occitan',
+  or: 'Oriya',
+  om: 'Oromo (Afan, Galla)',
+  ps: 'Pashto (Pushto)',
+  pl: 'Polish',
+  pt: 'Portuguese',
+  pa: 'Punjabi',
+  qu: 'Quechua',
+  rm: 'Rhaeto-Romance',
+  ro: 'Romanian',
+  ru: 'Russian',
+  sm: 'Samoan',
+  sg: 'Sangro',
+  sa: 'Sanskrit',
+  sr: 'Serbian',
+  sh: 'Serbo-Croatian',
+  st: 'Sesotho',
+  tn: 'Setswana',
+  sn: 'Shona',
+  sd: 'Sindhi',
+  si: 'Sinhalese',
+  ss: 'Siswati',
+  sk: 'Slovak',
+  sl: 'Slovenian',
+  so: 'Somali',
+  es: 'Spanish',
+  su: 'Sundanese',
+  sw: 'Swahili (Kiswahili)',
+  sv: 'Swedish',
+  tl: 'Tagalog',
+  tg: 'Tajik',
+  ta: 'Tamil',
+  tt: 'Tatar',
+  te: 'Telugu',
+  th: 'Thai',
+  bo: 'Tibetan',
+  ti: 'Tigrinya',
+  to: 'Tonga',
+  ts: 'Tsonga',
+  tr: 'Turkish',
+  tk: 'Turkmen',
+  tw: 'Twi',
+  ug: 'Uighur',
+  uk: 'Ukrainian',
+  ur: 'Urdu',
+  uz: 'Uzbek',
+  vi: 'Vietnamese',
+  vo: 'Volapük',
+  cy: 'Welsh',
+  wo: 'Wolof',
+  xh: 'Xhosa',
+  yi: 'Yiddish',
+  yo: 'Yoruba',
+  zu: 'Zulu',
+}
+
+export const languagesByName = Object.fromEntries(
+  Object.entries(languages).map(([code, language]) => [language, code]),
+)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@01-edu/shared",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "",
   "scripts": {
@@ -9,10 +9,12 @@
   "files": [
     "./bin/check-definitions.js",
     "./event-utils.js",
-    "./event-utils.js",
     "./lodash.deburr.js",
     "./onboarding.js",
-    "./onboarding.js",
+    "./attrs.js",
+    "./attrs-defs.js",
+    "./languages.js",
+    "./definitions-checker.js",
     "./path.js",
     "./programming-languages.js",
     "./score.js",