validate-npm-package-name 源码学习前言本文参加了由公众号@若川视野发起的每周源码共读活动

前言

本文参加了由公众号@若川视野发起的每周源码共读活动，点击了解详情一起参与。
这是源码共读的第7期，链接：validate-npm-package-name 检测 npm 包是否符合标准

学习目标

了解 validate-npm-package-name 的作用和使用场景
分析源码具体实现

使用示例

有效名称

var validate = require("validate-npm-package-name")

validate("some-package")
validate("example.com")
validate("under_score")
validate("123numeric")
validate("@npm/thingy")
validate("@jane/foo.js")

以上包名有效，会得到以下结果：

{
  validForNewPackages: true,
  validForOldPackages: true
}

有冲突的无效名称

validate("fs")

以上包名与node 内置模块冲突，会得到以下结果：

{
  validForNewPackages: false,
  validForOldPackages: true,
  warnings: [
    'fs is a core module name'
  ]
}

无效名称

validate(" leading-space:and:weirdchars")

以上包名无效，会得到以下结果：

{
  validForNewPackages: false,
  validForOldPackages: true,
  errors: [
    'name cannot contain leading or trailing spaces',
    'name can only contain URL-friendly characters'
  ]
}

源码分析

代码结构

var scopedPackagePattern = new RegExp('^(?:@([^/]+?)[/])?([^/]+?)$')
var builtins = require('builtins')
var blacklist = [
  'node_modules',
  'favicon.ico'
]
var validate = module.exports = function (name) {
   // 校验结果收集变量
   var warnings = []
   var errors = []
   // ... 核心代码
}
var done = function (warnings, errors) {
  // ... 校验结果构造
  return result
}

总结一下就是

接收一个字符串，检测该字符串是否有效包名
构造检测结果并返回

规则检验函数 `validate`

规则如下：

支持scope package，如@npm/thingy
不能以 _ or .开头
不能包含前空格或后空格
不能为保留字
不能与node内置模块冲突
包名超长警告
特殊字符"~'!()*"警告
禁止任何非 url 安全字符

边界处理

  // 边界判断： 非空
  if (name === null) {
    errors.push('name cannot be null')
    return done(warnings, errors)
  }
  // 边界判断： 非undefined
  if (name === undefined) {
    errors.push('name cannot be undefined')
    return done(warnings, errors)
  }
  // 边界判断： 字符串类型检测
  if (typeof name !== 'string') {
    errors.push('name must be a string')
    return done(warnings, errors)
  }

字符串约定边界处理

  // 不能为空字符串
  if (!name.length) {
    errors.push('name length must be greater than zero')
  }
  // 不能以 . 开头
  if (name.match(/^\./)) {
    errors.push('name cannot start with a period')
  }
  // 不能以 _ 开头
  if (name.match(/^_/)) {
    errors.push('name cannot start with an underscore')
  }
  // 头尾不能有空白符
  if (name.trim() !== name) {
    errors.push('name cannot contain leading or trailing spaces')
  }

手动屏蔽名单

  blacklist.forEach(function (blacklistedName) {
    if (name.toLowerCase() === blacklistedName) {
      errors.push(blacklistedName + ' is a blacklisted name')
    }
  })

这里主要是处理公共规范

是否为内置模块

  builtins.forEach(function (builtin) {
    if (name.toLowerCase() === builtin) {
      warnings.push(builtin + ' is a core module name')
    }
  })

警告处理

  // 超长警告
  if (name.length > 214) {
    warnings.push('name can no longer contain more than 214 characters')
  }
  // 混合大小写警告
  if (name.toLowerCase() !== name) {
    warnings.push('name can no longer contain capital letters')
  }
  // 混合大小写警告
  if (/[~'!()*]/.test(name.split('/').slice(-1)[0])) {
    warnings.push('name can no longer contain special characters ("~\'!()*")')
  }

禁止非 url 安全字符，但支持作用域包命名形式

  if (encodeURIComponent(name) !== name) {
    // 作用域包命名形式
    var nameMatch = name.match(scopedPackagePattern)
    if (nameMatch) {
      var user = nameMatch[1]
      var pkg = nameMatch[2]
      if (encodeURIComponent(user) === user && encodeURIComponent(pkg) === pkg) {
        return done(warnings, errors)
      }
    }

    errors.push('name can only contain URL-friendly characters')
  }

关于 scopedPackagePattern 可以参考以下网址做分析

正则表达式可视化，链接地址：jex.im/regulex/

微信截图_20220717112734.png

构造检测结果 done 函数

var done = function (warnings, errors) {
  var result = {
    validForNewPackages: errors.length === 0 && warnings.length === 0,
    validForOldPackages: errors.length === 0,
    warnings: warnings,
    errors: errors
  }
  if (!result.warnings.length) delete result.warnings
  if (!result.errors.length) delete result.errors
  return result
}

总结

整个项目不难，但是逻辑清晰，先处理边界再处理核心规则，另外封装一个检测结果的构造函数，把检测结果尽可能的收集再返回给外部使用，方便外部调用时对结果进行分析。

validate-npm-package-name 源码学习

前言