module-replacements 1.0.0 → 2.0.0-beta.1

package/README.md

@@ -1,9 +1,19 @@
 # module-replacements
 
-This package provides a set of manifests which each define a mapping of
-JS modules to their suggested replacements.
+This project provides two things:
 
-## Usage
+- A JS package containing manifests of suggested module replacements
+- Documentation for replacements which are not entirely replaced by native
+functionality
+
+## Replacements documentation
+
+You can read more about module replacements and browse the list
+[by clicking here](./docs/modules/README.md).
+
+## `module-replacements` package
+
+### Usage
 
 You can install this package via NPM:
 
@@ -17,16 +27,16 @@ You can then import the manifest of your choice:
 import {NativeReplacements} from 'module-replacements';
 ```
 
-## Manifests
+### Manifests
 
 We provide three manifests:
 
 - All (includes every manifest)
-- Native replacements (modules which can be replaced by native equivalents)
-- Optimisation replacements (modules which can be replaced by leaner or
-closer-to-the-platform equivalents)
+- Native replacements
+- Micro utility replacements
+- Preferred replacements
 
-### Native replacements
+#### Native replacements
 
 These are modules which can now be replaced by native functionality.
 
@@ -36,19 +46,20 @@ platform features can be replaced by their platform equivalents.
 Similarly, features which did not exist at the time but have now existed in
 the platform for many years, so no longer need a dependency.
 
-### Optimisation replacements
+#### Micro utility replacements
 
-These are modules which have more optimal replacements.
+This is a more opinionated list of modules considered to be 'micro utilities' -
+very small utilities which could possibly be replaced with native equivalents
+or removed entirely.
 
-For example, some modules have arguably unnecessarily deep dependencies trees,
-or rely on functionality themselves which fit into the "Native replacements"
-category. These should likely be replaced by leaner alternatives.
+#### Preferred replacements
 
-Another example - modules which are too granularly modularised, leading to
-unnecessarily large amounts of small dependencies (aka "micro dependencies").
+This is a very opinionated list of modules with preferred replacements. Often
+these replacements are much lighter or more modern than the modules they are
+replacing.
 
-Due to this being a one-to-many mapping (there are often many possible
-replacements), this list can contain multiple replacements per module.
+Sometimes these may also be forks of older packages which are actively
+maintained (unlike the source module).
 
 # Contributing
 

package/dist/commonjs/main.d.ts

@@ -1,18 +1,6 @@
-export interface ManifestModule {
-    id: string;
-    replacements: string[];
-}
-export interface ManifestReplacement {
-    id: string;
-    native?: boolean;
-    example: string;
-    url: string;
-}
-export interface Manifest {
-    modules: ManifestModule[];
-    replacements: ManifestReplacement[];
-}
-declare const nativeReplacements: Manifest;
-declare const optimisationReplacements: Manifest;
-export { nativeReplacements, optimisationReplacements };
-export declare const all: Manifest;
+import { ManifestModule } from './types.js';
+declare const nativeReplacements: ManifestModule;
+declare const microUtilsReplacements: ManifestModule;
+declare const preferredReplacements: ManifestModule;
+export { nativeReplacements, microUtilsReplacements, preferredReplacements };
+export declare const all: ManifestModule;

package/dist/commonjs/main.js

@@ -3,14 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.all = exports.optimisationReplacements = exports.nativeReplacements = void 0;
+exports.all = exports.preferredReplacements = exports.microUtilsReplacements = exports.nativeReplacements = void 0;
 const native_json_1 = __importDefault(require("../manifests/native.json"));
-const optimisation_json_1 = __importDefault(require("../manifests/optimisation.json"));
+const micro_utilities_json_1 = __importDefault(require("../manifests/micro-utilities.json"));
+const preferred_json_1 = __importDefault(require("../manifests/preferred.json"));
 const nativeReplacements = native_json_1.default;
 exports.nativeReplacements = nativeReplacements;
-const optimisationReplacements = optimisation_json_1.default;
-exports.optimisationReplacements = optimisationReplacements;
+const microUtilsReplacements = micro_utilities_json_1.default;
+exports.microUtilsReplacements = microUtilsReplacements;
+const preferredReplacements = preferred_json_1.default;
+exports.preferredReplacements = preferredReplacements;
 exports.all = {
-    modules: [...native_json_1.default.modules, ...optimisation_json_1.default.modules],
-    replacements: [...native_json_1.default.replacements, ...optimisation_json_1.default.replacements]
+    moduleReplacements: [
+        ...nativeReplacements.moduleReplacements,
+        ...microUtilsReplacements.moduleReplacements,
+        ...preferredReplacements.moduleReplacements
+    ]
 };

package/dist/commonjs/types.d.ts

@@ -0,0 +1,27 @@
+interface ModuleReplacementLike {
+    type: string;
+    moduleName: string;
+    category?: string;
+}
+interface DocumentedModuleReplacement extends ModuleReplacementLike {
+    type: 'documented';
+    docPath: string;
+}
+interface NativeModuleReplacement extends ModuleReplacementLike {
+    type: 'native';
+    mdnPath: string;
+    nodeVersion: string;
+    replacement: string;
+}
+interface SimpleModuleReplacement extends ModuleReplacementLike {
+    type: 'simple';
+    replacement: string;
+}
+interface NoModuleReplacement extends ModuleReplacementLike {
+    type: 'none';
+}
+type ModuleReplacement = DocumentedModuleReplacement | NativeModuleReplacement | SimpleModuleReplacement | NoModuleReplacement;
+export interface ManifestModule {
+    moduleReplacements: ModuleReplacement[];
+}
+export {};

package/dist/commonjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/main.d.ts

@@ -1,18 +1,6 @@
-export interface ManifestModule {
-    id: string;
-    replacements: string[];
-}
-export interface ManifestReplacement {
-    id: string;
-    native?: boolean;
-    example: string;
-    url: string;
-}
-export interface Manifest {
-    modules: ManifestModule[];
-    replacements: ManifestReplacement[];
-}
-declare const nativeReplacements: Manifest;
-declare const optimisationReplacements: Manifest;
-export { nativeReplacements, optimisationReplacements };
-export declare const all: Manifest;
+import { ManifestModule } from './types.js';
+declare const nativeReplacements: ManifestModule;
+declare const microUtilsReplacements: ManifestModule;
+declare const preferredReplacements: ManifestModule;
+export { nativeReplacements, microUtilsReplacements, preferredReplacements };
+export declare const all: ManifestModule;

package/dist/esm/main.js

@@ -1,9 +1,14 @@
 import native from '../manifests/native.json';
-import optimisation from '../manifests/optimisation.json';
+import microUtils from '../manifests/micro-utilities.json';
+import preferred from '../manifests/preferred.json';
 const nativeReplacements = native;
-const optimisationReplacements = optimisation;
-export { nativeReplacements, optimisationReplacements };
+const microUtilsReplacements = microUtils;
+const preferredReplacements = preferred;
+export { nativeReplacements, microUtilsReplacements, preferredReplacements };
 export const all = {
-    modules: [...native.modules, ...optimisation.modules],
-    replacements: [...native.replacements, ...optimisation.replacements]
+    moduleReplacements: [
+        ...nativeReplacements.moduleReplacements,
+        ...microUtilsReplacements.moduleReplacements,
+        ...preferredReplacements.moduleReplacements
+    ]
 };

package/dist/esm/types.d.ts

@@ -0,0 +1,27 @@
+interface ModuleReplacementLike {
+    type: string;
+    moduleName: string;
+    category?: string;
+}
+interface DocumentedModuleReplacement extends ModuleReplacementLike {
+    type: 'documented';
+    docPath: string;
+}
+interface NativeModuleReplacement extends ModuleReplacementLike {
+    type: 'native';
+    mdnPath: string;
+    nodeVersion: string;
+    replacement: string;
+}
+interface SimpleModuleReplacement extends ModuleReplacementLike {
+    type: 'simple';
+    replacement: string;
+}
+interface NoModuleReplacement extends ModuleReplacementLike {
+    type: 'none';
+}
+type ModuleReplacement = DocumentedModuleReplacement | NativeModuleReplacement | SimpleModuleReplacement | NoModuleReplacement;
+export interface ManifestModule {
+    moduleReplacements: ModuleReplacement[];
+}
+export {};

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "module-replacements",
   "description": "This package provides a set of manifests which each define a mapping of JS modules to their suggested replacements.",
-  "version": "1.0.0",
+  "version": "2.0.0-beta.1",
   "main": "./dist/commonjs/main.js",
   "scripts": {
     "clean": "rimraf dist main.js",
@@ -9,7 +9,9 @@
     "format": "prettier --write \"./src/**/*.ts\" \"./manifests/**/*.json\"",
     "build:types": "tsc --noEmit",
     "build:bundle": "esbuild src/main.ts --format=esm --outfile=main.js --bundle",
-    "build": "npm run clean && npm run build:bundle && npm run build:types"
+    "build": "npm run clean && npm run build:bundle && npm run build:types",
+    "validate-manifests": "node scripts/validate-manifests.js",
+    "generate-schema": "node scripts/generate-schema.js"
   },
   "tshy": {
     "exports": {
@@ -31,9 +33,11 @@
   },
   "homepage": "https://github.com/es-tooling/module-replacements#readme",
   "devDependencies": {
+    "ajv": "^8.16.0",
     "esbuild": "^0.20.0",
     "prettier": "^3.2.4",
     "rimraf": "^5.0.5",
+    "ts-json-schema-generator": "^2.3.0",
     "tshy": "^1.11.0",
     "typescript": "^5.3.3"
   },