docs: add version reference

[MarlonPassos-git]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

In this PR, I added the @version tag in the JSDoc of functions to provide a reference for when each function was introduced.

I used the file radashi/dist/esm/index.mjs from npm as a base to identify which functions were available in version 12.1.0. For functions that were not present in that version, I assigned them the 12.2.0 tag. Although version 12.2.0 has not been released yet, I decided to add the tag in advance to maintain consistency with "official" versions.

Additionally, I updated the .mdx files by adding a new since property. This will allow us to integrate this information into the documentation project later on.

I plan to open a follow-up PR in the documentation project with my suggestions for incorporating this information.

As a side note, I used a workaround script to assist in generating the changes:

addVersionInTsFile.cjs

const fs = require('fs');
const path = require('path');

const functionsVersion1210 = [
  'alphabetical', 'boil', 'cluster', 'counting', 'diff', 'first', 'flat', 'fork', 'group', 'intersects', 'iterate', 'last', 'list', 'max', 'merge', 'min', 'objectify', 'range', 'replace', 'replaceOrAppend', 'select', 'shift', 'sift', 'sort', 'sum', 'toggle', 'unique', 'zip', 'zipToObject',
  'all', 'defer', 'guard', 'map', 'parallel', 'reduce', 'retry', 'sleep', 'tryit', 'try',
  'callable', 'chain', 'compose', 'debounce', 'memo', 'partial', 'partob', 'proxied', 'throttle',
  'inRange', 'toFloat', 'toInt',
  'assign', 'clone', 'construct', 'crush', 'get', 'invert', 'keys', 'listify', 'lowerize', 'mapEntries', 'mapKeys', 'mapValues', 'omit', 'pick', 'set', 'shake', 'upperize',
  'draw', 'random', 'shuffle', 'uid',
  'series',
  'camel', 'capitalize', 'dash', 'pascal', 'snake', 'template', 'title', 'trim',
  'isArray', 'isDate', 'isEmpty', 'isEqual', 'isFloat', 'isFunction', 'isInt', 'isNumber', 'isObject', 'isPrimitive', 'isPromise', 'isString', 'isSymbol'
];


function getAllTsFiles(dir, fileList = []) {
  const files = fs.readdirSync(dir);
  files.forEach(file => {
    const filePath = path.join(dir, file);
    if (fs.statSync(filePath).isDirectory()) {
      getAllTsFiles(filePath, fileList);
    } else if (filePath.endsWith('.ts')) {
      fileList.push(filePath);
    }
  });
  return fileList;
}

function addVersionTag(filePath) {
  const content = fs.readFileSync(filePath, 'utf8');
  const lines = content.split('\n');
  let modified = false;

  const functionName = path.basename(filePath, '.ts');
  const version = functionsVersion1210.includes(functionName) ? '12.1.0' : '12.2.0';

  for (let i = 0; i < lines.length; i++) {
    if (lines[i].startsWith('/**')) {
      const endOfJsDoc = lines.slice(i).findIndex(line => line.startsWith(' */'));
      if (endOfJsDoc !== -1) {
        lines.splice(i + endOfJsDoc, 0, ` * @version ${version}`);
        modified = true;
        console.log(`Tag "@version ${version}" adicionada em ${filePath}`);
        break;
      }
    }
  }
  if (modified) {
    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
  }
}


const srcDir = path.join(__dirname, 'src');
const tsFiles = getAllTsFiles(srcDir);
console.log(`Total de arquivos .ts encontrados: ${tsFiles.length}`);
tsFiles.forEach(addVersionTag);

addVersionInTsFile.cjs

const fs = require('fs');
const path = require('path');

const functionsVersion1210 = [
  'alphabetical', 'boil', 'cluster', 'counting', 'diff', 'first', 'flat', 'fork', 'group', 'intersects', 'iterate', 'last', 'list', 'max', 'merge', 'min', 'objectify', 'range', 'replace', 'replaceOrAppend', 'select', 'shift', 'sift', 'sort', 'sum', 'toggle', 'unique', 'zip', 'zipToObject',
  'all', 'defer', 'guard', 'map', 'parallel', 'reduce', 'retry', 'sleep', 'tryit', 'try',
  'callable', 'chain', 'compose', 'debounce', 'memo', 'partial', 'partob', 'proxied', 'throttle',
  'inRange', 'toFloat', 'toInt',
  'assign', 'clone', 'construct', 'crush', 'get', 'invert', 'keys', 'listify', 'lowerize', 'mapEntries', 'mapKeys', 'mapValues', 'omit', 'pick', 'set', 'shake', 'upperize',
  'draw', 'random', 'shuffle', 'uid',
  'series',
  'camel', 'capitalize', 'dash', 'pascal', 'snake', 'template', 'title', 'trim',
  'isArray', 'isDate', 'isEmpty', 'isEqual', 'isFloat', 'isFunction', 'isInt', 'isNumber', 'isObject', 'isPrimitive', 'isPromise', 'isString', 'isSymbol'
];

function getAllMdxFiles(dir, fileList = []) {
  const files = fs.readdirSync(dir);
  files.forEach(file => {
    const filePath = path.join(dir, file);
    if (fs.statSync(filePath).isDirectory()) {
      getAllMdxFiles(filePath, fileList);
    } else if (filePath.endsWith('.mdx')) {
      fileList.push(filePath);
    }
  });
  return fileList;
}

function addSinceTag(filePath) {
  const content = fs.readFileSync(filePath, 'utf8');
  if (!content.includes('since:')) {
    const lines = content.split('\n');
    const descriptionIndex = lines.findIndex(line => line.startsWith('description:'));
    if (descriptionIndex !== -1) {
      const titleLine = lines.find(line => line.startsWith('title:'));
      const functionName = titleLine ? titleLine.split(':')[1].trim() : '';
      const version = functionsVersion1210.includes(functionName) ? '12.1.0' : '12.2.0';
      lines.splice(descriptionIndex + 1, 0, `since: ${version}`);
      fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
      console.log(`Tag "since: ${version}" adicionada em ${filePath}`);
    }
  }
}

const docsDir = path.join(__dirname, 'docs');

const mdxFiles = getAllMdxFiles(docsDir);
mdxFiles.forEach(addSinceTag);

Related issue, if any:

#243 (comment)
radashi-org/radashi-org.github.io#3

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed
• Related benchmarks have been added or updated, if needed

Does this PR introduce a breaking change?

No

[aleclarson]

You are on fire 🔥 This looks great.