{"id":43020680,"url":"https://github.com/data-fair/lib","last_synced_at":"2026-01-31T06:30:46.183Z","repository":{"id":65890574,"uuid":"601693093","full_name":"data-fair/lib","owner":"data-fair","description":"A collection of javascript functions, components, types, etc to help work inside the data-fair stack.","archived":false,"fork":false,"pushed_at":"2026-01-12T09:57:04.000Z","size":3649,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-12T18:49:31.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/data-fair.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-14T16:05:21.000Z","updated_at":"2026-01-12T09:57:03.000Z","dependencies_parsed_at":"2023-11-30T11:30:40.652Z","dependency_job_id":"63cfca53-c2c5-4541-94b5-c69f4201b305","html_url":"https://github.com/data-fair/lib","commit_stats":{"total_commits":63,"total_committers":1,"mean_commits":63.0,"dds":0.0,"last_synced_commit":"23987c941cf4781b4e8edf8f818411c35109310e"},"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"purl":"pkg:github/data-fair/lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/data-fair%2Flib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/data-fair%2Flib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/data-fair%2Flib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/data-fair%2Flib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/data-fair","download_url":"https://codeload.github.com/data-fair/lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/data-fair%2Flib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28931247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T04:05:25.756Z","status":"ssl_error","status_checked_at":"2026-01-31T04:02:35.005Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-31T06:30:45.547Z","updated_at":"2026-01-31T06:30:46.163Z","avatar_url":"https://github.com/data-fair.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @data-fair/lib\n\nA collection of npm modules to share functions, types, UI components, etc accross the data-fair stack. Modules are managed in npm workspaces and published inside the namespace @data-fair with the \"lib-\" prefix.\n\n## @data-fair/lib-utils\n\nAny standalone piece of code that has no dependency or only very little ones.\n\n## @data-fair/lib-types-builder\n\nA tool to process json schemas and produce types, validation functions, etc.\n\n## @data-fair/lib-validation\n\nFunctions related to the application of validation functions to data.\n\n## @data-fair/lib-common-types\n\nShared schemas and built type definitions, etc.\n\n## @data-fair/lib-node\n\nCode meant to be used server-side in a nodejs environment.\n\n## @data-fair/lib-express\n\nCode meant to be used server-side in a Express based Web server.\n\n## @data-fair/lib-vue\n\nCode meant to be used in a Vue application, mostly composables.\n\n## @data-fair/lib-vuetify\n\nComponents based on the Vuetify 3 UI lib.\n\n## @data-fair/lib/lib-processing-dev\n\nCode meant to be used in the development environment of a processing.\n\n## Types\n\nSome shared contracts, typescript types, etc.\n\n### SessionState\n\nDescribes the current session, the logged in user, their organizations, etc. Usually used on the client side through useSession and on the server side through the session middleware.\n\n```ts\nimport { type SessionState } from '@data-fair/lib/types/session-state'\n```\n\n### build.ts\n\n\nThis module implements a strategy similar to [Fastify](https://www.fastify.io/docs/latest/Reference/Validation-and-Serialization/) for validation and serialization. But it is a simple optional tool used to improve our apis, not a framework.\n\n  - validation of body and query is encouraged (headers are not usually included because they are much less frequently manipulated on a per-route basis)\n  - type casting : the schemas act as type guards\n  - fast response serialization using [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify)\n  - use json-schema-to-typescript to create coherent schemas and types\n  - a provided script helps building a typescript module with types, compiled validation function and compiled serialization function\n\nCreate a directory structure compatible with the build script:\n\n```\ntypes/\n├── my-type\n│   └── schema.json\n\n```\n\nSchemas can contain instructions to generate optional functionalities:\n```json\n  \"x-exports\": [\"types\", \"validate\", \"stringify\", \"schema\"],\n```\n\nIn the types directory install build peer dependencies:\n```sh\nnpm i -D ajv ajv-formats ajv-errors fast-json-stringify json-schema-to-typescript @bcherny/json-schema-ref-parser\n```\n\nIn the types directory's package.json create this script:\n\n```json\n  \"scripts\": {\n    \"build\": \"node node_modules/@data-fair/lib/types/build.js ./ \u0026\u0026 tsc\"\n  },\n```\n\nRunning this script should fill the types directory like so:\n\n```\ntypes/\n├── my-type\n│   ├── index.d.ts\n│   ├── index.js\n│   ├── index.ts\n│   ├── schema.json\n│   └── validate.js\n```\n\nIn the nodejs service, install peer dependencies:\n\n```sh\nnpm i ajv-i18n flatstr\n```\n\nThen in a route use the built modules:\n\n```ts\nimport * as myBodySchema from 'types/my-body'\nimport * as myQuerySchema from 'types/my-query'\nimport * as myResponseSchema from 'types/my-response'\n\nrouter.post('', asyncHandler(async (req, res) =\u003e {\n  // after these lines body and query will be typed and the schema will be validated\n  // a 400 error is thrown in case of failure\n  const body = myQuerySchema.validate(req.body, req.session.lang, 'body')\n  const query = myQuerySchema.validate(req.query, req.session.lang, 'query')\n  \n  const result = await ...\n\n  res.type('json').send(myResponseSchema.stringify(result))\n}))\n```\n\n## Vue\n\n### useSession\n\nThis composable for Vue 3 provides a reactive session state and useful methods (login, logout, etc).\n\nInstall peer dependencies:\n\n```sh\nnpm i ofetch jwt-decode debug universal-cookie\n```\n\nUse as a nuxt plugin in js (plugins/session.js):\n\n```ts\nimport { useSession } from '@data-fair/lib/vue/use-session'\n\nexport default defineNuxtPlugin(async (nuxtApp) =\u003e {\n  const session = await useSession({req: nuxtApp.ssrContext?.event.node.req})\n  return { provide: { session } }\n})\n```\n\nUse as a nuxt plugin in typescript (plugins/session.ts):\n\n```ts\nimport { useSession, type Session } from '@data-fair/lib/vue/use-session'\n\ndeclare module '#app' {\n  interface NuxtApp {\n    $session: Session\n  }\n}\ndeclare module 'vue' {\n  interface ComponentCustomProperties {\n    $session: Session\n  }\n}\n\nexport default defineNuxtPlugin(async (nuxtApp) =\u003e {\n  const session = await useSession({req: nuxtApp.ssrContext?.event.node.req})\n  return { provide: { session } }\n})\n\n```\n\n## Nuxt\n\nWe provide a Nuxt module to help bootstrap a nuxt project with vuetify and our own composables.\n\n## Express\n\n### session\n\nThis middleware provides a thin layer for connecting to simple-directory using jwks, validating session tokens and casting to the SessionState type (see section payload). This module extends the standard express Request type to add the session property, this way all access to req.session is fully typed and safe.\n\nInstall peer dependencies:\n\n```sh\nnpm i jsonwebtoken jwks-rsa cookie\n```\n\n```ts\nimport { asyncHandler, initSession } from '@data-fair/lib/express/index.js'\nexport const app = express()\nconst session = initSession({ directoryUrl: config.directoryUrl })\napp.use(session.auth)\n\nrouter.get('', asyncHandler(async (req, res) =\u003e {\n  if (!req.session.account) { res.status(401).send(); return }\n  ...\n}))\n```\n\n## Nodejs\n\n### Observer\n\nVery light web server to expose prometheus metrics, export a cpu profile and maybe other incoming obervability features.\n\nInstall peer dependencies:\n\n```sh\nnpm i prom-client debug\n```\n\nRun a mini webserver to observability functionalities:\n\n```ts\nimport {startObserver, stopObserver} from '@data-fair/lib/node/observer.js'\n\n...\nawait startObserver(port) // default port is 9090\n\n...\nawait stopObserver()\n```\n\nIncrement the shared \"df_internal_error\" metric and produce a corresponding log:\n\n```ts\nimport { internalError } from '@data-fair/lib/node/observer.js'\n\ninternalError('http', 'failure while serving http request', err)\n```\n\nDefine a custom prometheus metric and use it:\n\n```ts\nconst myCounter = new Counter({\n  name: 'df_my_counter',\n  help: '...',\n  labelNames: ['myLabel']\n})\n\n...\nmyCounter.inc({myLabel: 'label value'})\n```\n\nDefine a custom service-level metric (a service-level metric value depends on a shared state of the system instead of only the activity of the current process):\n\n```ts\nimport { servicePromRegistry } from '@data-fair/lib/node/observer.js'\n\nnew client.Gauge({\n  name: 'df_my_gauge',\n  help: '...',\n  registers: [servicePromRegistry],\n  async collect () {\n    this.set(await db.collection('collection').estimatedDocumentCount())\n  }\n})\n```\n\n### Upgrade scripts\n\nScripts must be written in 'upgrade/{CURRENT VERSION}' directory. All scripts with a version number greater than or equal to the version of the service registered in the database will executed.\n\nThe scripts will be run automatically at startup of service.\n\nScripts are simple nodejs modules that export an object following UpgradeScript interface:\n\n  - description: A short description string.\n  - exec: An async function. It accepts a mongodb connection as first parameter and debug log method as second parameter.\n\nWARNING: theoretically all scripts are run only once. But this cannot be strictly ensured therefore scripts should be idempotent. It means that running them multiple times should not create problems.\n\nInstall peer dependencies:\n\n```sh\nnpm i semver debug\n```\n\nRun the scripts somewhere in app intialization:\n\n```ts\nimport upgradeScripts from '@data-fair/lib/node/upgrade-scripts.js'\n\nawait upgradeScripts(db)\n```\n\n\n## Processings\n\n### tests-utils.js\nThis utility provides a context generator for processing tests.\n\nInstall peer dependencies:\n\n```sh\nnpm i --save-dev dayjs ws draftlog axios\n```\n\nIn a classic processing test file, import with :\n```js\nimport testsUtils from '@data-fair/lib/processings/tests-utils.js'\n```\n\nOr for a commonjs processing test file, import with :\n```js\nconst testsUtils = require('@data-fair/lib/processings/tests-utils.js')\n```\n\nThen use the utility to generate a context and test the processing:\n```js\nconst context = testsUtils.context({\n  pluginConfig: {\n    apiKey: config.apiKey\n  },\n  processingConfig: {\n    datasetMode: 'create',\n    dataset: { title: 'Titre du jeu de donnée' },\n    // Autres paramètres de configuration\n  },\n  tmpDir: 'data'\n}, config, false)\n\nawait processing.run(context)\n```\n\n\n## Colors\n\n### colors.js\n\nA simple yet complete color palette generator.\n\nInstall peer dependencies :\n\n```sh\nnpm i chroma-js\n```\n\nUse case : you have a colorscheme, some data and want to generate an accompanying palette.\n\n**`getColors(colorscheme, data, size, vuetifyColors = null)`**\n- Generates a palette of colors from a given colorscheme, data and size.\n- If vuetifyColors is provided, the palette will be composed of the app's theme primary and secondary colors (case where the colorscheme type is vuetify-theme).\n- Returns an array of hex values.\n\n```js\nimport getColors from '@data-fair/lib/color-scheme/colors.js'\n\nconst colorscheme = {\n  type: 'qualitative',\n  name: 'Accent'\n}\nconst data = {\n  ... // some data\n}\n\nconst palette = getColors(colorscheme, data, data.results.length)\n```\n\nThe colorscheme is a standardized object that describes the colorscheme as a json-schema. More info about the structure it must follow can be found here : [`color-scheme/schema.json`](https://github.com/data-fair/lib/blob/main/src/color-scheme/schema.json)\n\n## Prompts\n\nThis directory contains example prompts for AI chats (tested with copilot chat).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdata-fair%2Flib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdata-fair%2Flib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdata-fair%2Flib/lists"}