@01-edu/shared 1.0.3 → 1.0.5

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/bin/check-definitions.js

@@ -5,24 +5,30 @@ import { readFile, stat } from 'node:fs/promises'
 import { checkAndBuildDefinitions } from '../definitions-checker.js'
 
 const auditValidation = validation => validation.type.endsWith('_audit')
-const result = await checkAndBuildDefinitions(async key => {
-  const referencePath = `content${key ? `/${key}` : ''}/def.json`
-  const def = JSON.parse(await readFile(referencePath, 'utf8'))
-  def.attrs || (def.attrs = {})
-  def.referencePath = referencePath
-  switch (def.type) {
-    case 'project':
-    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We want to fallthrough
-    case 'raid': {
-      await stat(`content/${key}/audit/README.md`)
+try {
+  const result = await checkAndBuildDefinitions(async key => {
+    const referencePath = `content${key ? `/${key}` : ''}/def.json`
+    const def = JSON.parse(await readFile(referencePath, 'utf8'))
+    def.attrs || (def.attrs = {})
+    def.referencePath = referencePath
+    switch (def.type) {
+      case 'project':
+      // biome-ignore lint/suspicious/noFallthroughSwitchClause: We want to fallthrough
+      case 'raid': {
+        await stat(`content/${key}/audit/README.md`)
+      }
+      case 'exercise': {
+        await stat(`content/${key}/README.md`)
+      }
     }
-    case 'exercise': {
-      await stat(`content/${key}/README.md`)
-    }
-  }
 
-  return def
-})
+    return def
+  })
+} catch ({ message, ...props }) {
+  console.error(message, props)
+  process.exit(1)
+}
 
+console.log('All checks passed, no errors')
 // Extra checks:
 // - Orphan files (defs files not referenced anywhere)

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.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "",
   "scripts": {
@@ -11,6 +11,9 @@
     "./event-utils.js",
     "./lodash.deburr.js",
     "./onboarding.js",
+    "./attrs.js",
+    "./attrs-defs.js",
+    "./languages.js",
     "./definitions-checker.js",
     "./path.js",
     "./programming-languages.js",