survey-data-dictionary

Biblioteca TypeScript pura para construir diccionarios de datos y usar esos diccionarios para interpretar respuestas. Recibe SurveyStructure; no analiza LimeSurvey, no hace solicitudes HTTP, no accede a Redis y no depende del navegador.

Instalación

npm install survey-data-dictionary survey-structure

Operaciones públicas

• buildSurveyDictionary(structure, options?): convierte una definición SurveyStructure en columnas de respuesta, valores permitidos y aliases.
• dictionaryToCsv(dictionary): serializa el mismo diccionario como CSV.
• translateResponse(dictionary, response): interpreta un registro de respuestas.
• translateDataset(dictionary, responses): interpreta varios registros.
• mapTabularDataset(dictionary, headers, rows, ignoredHeaders?, missingValues?): alinea un archivo tabular por posición sin perder encabezados repetidos.
• translatedDatasetToCsv(result): serializa el resultado traducido.

Generar un diccionario

El siguiente ejemplo es sintético:

import { buildSurveyDictionary, dictionaryToCsv } from 'survey-data-dictionary';
import type { SurveyStructure } from 'survey-structure';

const structure: SurveyStructure = {
  contractVersion: '2.0.0',
  id: 'survey-123',
  title: 'Encuesta de demostración',
  fields: [{
    id: 'q1',
    code: 'Q1',
    type: 'single-choice',
    label: 'Consentimiento',
    options: [
      { code: 'A1', label: 'Sí' },
      { code: 'A2', label: 'No' },
    ],
  }],
};

const dictionary = buildSurveyDictionary(structure);
const csv = dictionaryToCsv(dictionary);

La entrada describe la encuesta. La salida describe cómo leer sus respuestas:

{
  "contractVersion": "1.0.0",
  "surveyId": "survey-123",
  "fields": [{
    "questionCode": "Q1",
    "questionLabel": "Consentimiento",
    "responseKey": "Q1",
    "dataType": "code",
    "cardinality": "single",
    "values": [
      { "code": "A1", "label": "Sí" },
      { "code": "A2", "label": "No" }
    ]
  }],
  "issues": []
}

responseKey es la clave canónica que debe buscarse en un registro de respuestas. Los aliases manuales se declaran como encabezado externo → responseKey:

buildSurveyDictionary(structure, {
  aliases: { external_consent_column: 'Q1' },
});

Los campos estructuralmente inválidos producen incidencias. Con { strict: true }, cualquier incidencia de nivel error detiene la generación.

Traducir una respuesta

import { translateResponse } from 'survey-data-dictionary';

const result = translateResponse(dictionary, { Q1: 'A1' });

Salida abreviada:

{
  "fields": [{
    "responseKey": "Q1",
    "questionCode": "Q1",
    "questionLabel": "Consentimiento",
    "dataType": "code",
    "sourceValue": "A1",
    "displayValue": "Sí",
    "missing": false
  }],
  "issues": []
}

sourceValue conserva el dato recibido y displayValue contiene su etiqueta legible. missing es true únicamente cuando el valor no llegó, es null o es una cadena vacía. Si el código no existe en el diccionario, la biblioteca lo conserva como displayValue y agrega UNKNOWN_RESPONSE_VALUE; no inventa una etiqueta.

Traducir un dataset

SurveyResponseRecord representa un registro y SurveyResponseDataset = SurveyResponseRecord[] representa la colección de entrada:

import {
  translateDataset,
  translatedDatasetToCsv,
  type SurveyResponseDataset,
} from 'survey-data-dictionary';

const responses: SurveyResponseDataset = [
  { Q1: 'A1' },
  { Q1: 'A2' },
  { Q1: null },
];

const translated = translateDataset(dictionary, responses);
const translatedCsv = translatedDatasetToCsv(translated);

El dataset sólo contiene respuestas; no vuelve a incluir la definición de la encuesta. El diccionario aporta las etiquetas y reglas necesarias para interpretarlas.

Dataset tabular

Cuando una exportación se lee como encabezados y filas, la biblioteca puede alinearla sin convertir antes cada fila manualmente:

import { mapTabularDataset } from 'survey-data-dictionary';

const mapped = mapTabularDataset(
  dictionary,
  ['Response ID', 'Q1'],
  [[1, 'A1'], [2, 'A2']],
  ['Response ID'],
  ['', 'N/A'],
);

const translated = translateDataset(dictionary, mapped.responses);

La lista missingValues es explícita: sólo los valores proporcionados se normalizan a null. Los encabezados desconocidos se reportan como incidencias y las columnas repetidas se relacionan por posición.

Verificación local

npm run demo
npm test
npm run pack:dry-run