ماذا / لماذا

للأفضل أو للأسوأ ، ينمو المحتوى داخل package.json مع تعقيد أكبر وأكبر. في الأيام الوليدة لـ npm ، كان الملف مجرد بعض البيانات الوصفية عن التبعيات التي يعتمد عليها المشروع / الحزمة. نمت المشاريع من حيث التعقيد والآن أصبحت الاختبارات والأطر والمكتبات الأخرى كلها تبعيات ستظهر جالسة معًا. كان هناك بعض الانفصال بين dependencies و devDependencies ، لكن هذا تصنيف تقريبي. لدينا الآن أدوات تساهم وتؤمن داخل package.json مع تعقيد أكبر ... تكوينات monorepo ، تكوينات lint ، تكوينات الالتزام ، git hooks ، nodemon ، jest ، والقائمة تطول ...

تقدم التعليقات طريقة لشرح كل التعقيدات.

ما زلت أعتقد أن المشرفين على المكتبات يجب أن يظلوا يستخدمون JSON الخالص للتوافق مع الإصدارات السابقة ، ولكن على الأقل تقديم هذا المضي قدمًا سيسمح لمنشئي المشروع (الغالبية العظمى من المستخدمين) بالقدرة على توثيق حزمتهم. json. تم منحه ، يسمح json للمفاتيح المكررة بالعمل كتعليقات ، لكن هذا يشبه إلى حد كبير الاختراق.

كيف

السلوك الحالي

مثال منقح ومفتعل:

{
  "name": "my-project",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "a bunch of scripts",
    "ci": "a bunch of scripts",
    "ci:local": "a bunch of scripts",
    "docsite": "a bunch of scripts",
    "docsite:combiner": "a bunch of scripts",
    "docsite:sassdoc": "a bunch of scripts",
    "docsite:tsdoc": "a bunch of scripts",
    "e2e": "a bunch of scripts",
    "html-sketchapp-install": "a bunch of scripts",
    "html-sketchapp": "a bunch of scripts",
    "lint": "a bunch of scripts",
    "sassdoc": "a bunch of scripts",
    "sassdoc:comp": "a bunch of scripts",
    "sassdoc:core": "a bunch of scripts",
    "start": "a bunch of scripts",
    "start:hmr": "a bunch of scripts",
    "start:qa": "a bunch of scripts",
    "start:dev": "a bunch of scripts",
    "generate-examples": "a bunch of scripts",
    "rebuild-markdown": "a bunch of scripts",
    "watch-examples": "a bunch of scripts",
    "test:cov": "a bunch of scripts",

    "test": "jest",
    "test:watch": "jest --watch",
    "test:cc": "jest --coverage"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "dependencies": {
    "@angular-devkit/build-angular": "~0.900.1",
    "@angular-devkit/build-ng-packagr": "~0.900.1",
    "@angular-devkit/core": "~9.0.0",
    "@angular-devkit/schematics": "~9.0.0",
    "@angular/animations": "~9.0.0",
    "@angular/cdk": "~9.0.0",
    "@angular/cli": "~9.0.1",
    "@angular/common": "~9.0.0",
    "@angular/compiler": "~9.0.0",
    "@angular/compiler-cli": "~9.0.0",
    "@angular/core": "~9.0.0",
    "@angular/forms": "~9.0.0",
    "@angular/language-service": "~9.0.0",
    "@angular/platform-browser": "~9.0.0",
    "@angular/platform-browser-dynamic": "~9.0.0",
    "@angular/router": "~9.0.0",
    "@angular/service-worker": "~9.0.0",
    "@angularclass/hmr": "2.1.3",
    "@ngrx/effects": "~8.6.0",
    "@ngrx/entity": "~8.6.0",
    "@ngrx/router-store": "~8.6.0",
    "@ngrx/schematics": "~8.6.0",
    "@ngrx/store": "~8.6.0",
    "@ngrx/store-devtools": "~8.6.0",
    "@types/jasmine": "~3.5.0",
    "@types/jasminewd2": "~2.0.3",
    "@types/lodash-es": "^4.17.3",
    "@types/node": "^12.11.1",
    "classlist.js": "1.1.20150312",
    "codelyzer": "^5.1.2",
    "console-polyfill": "0.3.0",
    "core-js": "^2.5.4",
    "cz-conventional-changelog": "1.2.0",
    "date-fns": "1.30.1",
    "highcharts": "^7.2.1",
    "highcharts-angular": "^2.4.0",
    "html2canvas": "^1.0.0-rc.5",
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.4.2",
    "lodash-es": "^4.17.11",
    "mime": "~2.4.2",
    "ngrx-store-freeze": "0.2.4",
    "ngx-monaco-editor": "~8.0.0",
    "ngx-quill": "^7.3.12",
    "pdfmake": "^0.1.64",
    "prettier": "1.19.1",
    "protractor": "~5.4.3",
    "quill": "^1.3.7",
    "rxjs": "~6.5.4",
    "rxjs-compat": "^6.0.0",
    "standard-changelog": "1.0.19",
    "svgxuse": "1.2.6",
    "ts-node": "~8.3.0",
    "tsickle": "^0.35.0",
    "tslib": "^1.10.0",
    "tslint": "~5.18.0",
    "typescript": "~3.7.5",
    "web-animations-js": "~2.3.1",
    "zone.js": "~0.10.2"
  },
  "devDependencies": {
    "@types/jest": "^24.0.6",
    "jest": "^24.1.0",
    "jest-preset-angular": "^6.0.2",
    "ts-node": "~7.0.1",
    "typescript": "3.2.4"
  },
  "jest": {
    "preset": "jest-preset-angular",
    "setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
  },
  "nodemonConfig": {
    "ignore": [
      "**/example-module.ts"
    ],
    "watch": [
      "./a/bunch/of/stuff"
    ],
    "ext": "js ts md html"
  },
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": [
      "**"
    ]
  }
}

سلوك متوقع

مثال على package.json مع التعليقات.

{
  "name": "my-project",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "a bunch of scripts",
    "ci": "a bunch of scripts",
    "ci:local": "a bunch of scripts",
    // for building our documentation site
    "docsite": "a bunch of scripts",
    "docsite:combiner": "a bunch of scripts",
    "docsite:sassdoc": "a bunch of scripts",
    "docsite:tsdoc": "a bunch of scripts",
    "e2e": "a bunch of scripts",
    "lint": "a bunch of scripts",
    "sassdoc": "a bunch of scripts",
    "sassdoc:comp": "a bunch of scripts",
    "sassdoc:core": "a bunch of scripts",
    "start": "a bunch of scripts",
    "start:hmr": "a bunch of scripts",
    "start:qa": "a bunch of scripts",
    "start:dev": "a bunch of scripts",
    "generate-examples": "a bunch of scripts",
    "rebuild-markdown": "a bunch of scripts",
    "watch-examples": "a bunch of scripts",
    "test:cov": "a bunch of scripts",

    "test": "jest",
    "test:watch": "jest --watch",
    "test:cc": "jest --coverage"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "dependencies": {
    // ANGULAR
    "@angular-devkit/build-angular": "~0.900.1",
    "@angular-devkit/build-ng-packagr": "~0.900.1",
    "@angular-devkit/core": "~9.0.0",
    "@angular-devkit/schematics": "~9.0.0",
    "@angular/animations": "~9.0.0",
    "@angular/cdk": "~9.0.0",
    "@angular/cli": "~9.0.1",
    "@angular/common": "~9.0.0",
    "@angular/compiler": "~9.0.0",
    "@angular/compiler-cli": "~9.0.0",
    "@angular/core": "~9.0.0",
    "@angular/forms": "~9.0.0",
    "@angular/language-service": "~9.0.0",
    "@angular/platform-browser": "~9.0.0",
    "@angular/platform-browser-dynamic": "~9.0.0",
    "@angular/router": "~9.0.0",
    "@angular/service-worker": "~9.0.0",
    "@angularclass/hmr": "2.1.3",

    "zone.js": "~0.10.2",
    "rxjs": "~6.5.4",
    "rxjs-compat": "^6.0.0",


    // polyfills for angular 
    "console-polyfill": "0.3.0",
    "core-js": "^2.5.4",
    "classlist.js": "1.1.20150312",
    "svgxuse": "1.2.6",
    "web-animations-js": "~2.3.1",

    // lint management

    "codelyzer": "^5.1.2",
    "prettier": "1.19.1",
    "tslint": "~5.18.0",

    // changelog creation
    "cz-conventional-changelog": "1.2.0",
    "standard-changelog": "1.0.19",

    // ngrx state management 
    "@ngrx/effects": "~8.6.0",
    "@ngrx/entity": "~8.6.0",
    "@ngrx/router-store": "~8.6.0",
    "@ngrx/schematics": "~8.6.0",
    "@ngrx/store": "~8.6.0",
    "@ngrx/store-devtools": "~8.6.0",
    "ngrx-store-freeze": "0.2.4",


    // library deps

    // Graphs support
    "highcharts": "^7.2.1",
    "highcharts-angular": "^2.4.0",

    // for creating pdfs
    "html2canvas": "^1.0.0-rc.5",
    "pdfmake": "^0.1.64",

    // rich text support
    "ngx-quill": "^7.3.12",
    "quill": "^1.3.7",




    // testing
    "jasmine-core": "~3.5.0",
    "jasmine-spec-reporter": "~4.2.1",
    "karma": "~4.3.0",
    "karma-chrome-launcher": "~3.1.0",
    "karma-coverage-istanbul-reporter": "~2.1.0",
    "karma-jasmine": "~2.0.1",
    "karma-jasmine-html-reporter": "^1.4.2",

    // e2e testing
    "protractor": "~5.4.3",

    // typscript and compilation
    "ts-node": "~8.3.0",
    "tsickle": "^0.35.0",
    "tslib": "^1.10.0",
    "typescript": "~3.7.5",

    // misc deps
    "date-fns": "1.30.1",
    "lodash-es": "^4.17.11",
    "mime": "~2.4.2"
  },
  "devDependencies": {
    "@types/jasmine": "~3.5.0",
    "@types/jasminewd2": "~2.0.3",
    "@types/lodash-es": "^4.17.3",
    "@types/node": "^12.11.1",
    "@types/jest": "^24.0.6",
    "jest": "^24.1.0",
    "jest-preset-angular": "^6.0.2",
    "ts-node": "~7.0.1",
    "typescript": "3.2.4"
  },
  // complicated jest configuration here
  "jest": {
    "preset": "jest-preset-angular",
    "setupTestFrameworkScriptFile": "<rootDir>/setupJest.ts"
  },
  // use nodemon to trigger stuff
  "nodemonConfig": {
    "ignore": [
      "**/example-module.ts"
    ],
    "watch": [
      "./a/bunch/of/stuff"
    ],
    "ext": "js ts md html"
  },
  // extra libraries we are creating internally
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": [
      "**"
    ]
  }
}

مراجع

https://github.com/microsoft/node-jsonc-parser

يستخدم Typescript التعليقات في ملفات tsconfig.json الخاصة بهم.