cnpmcore

The NPM Registry API provides programmatic access to the registry's data and services. All communication is performed over HTTPS or HTTP using the registry.npmjs.org domain, and all data is exchanged in JSON format.

The API supports several core functional areas:

• Package: Operations related to package metadata and publishing.
• User: User-related information and management.
• Search: Querying the registry for packages.
• Token: Managing authentication tokens.
• Trend: Accessing trending package data.

$ curl -i https://registry.npmjs.org

HTTP/1.1 200 OK

{
  "db_name": "registry",
  "doc_count": 123772,
  "doc_del_count": 377,
  "update_seq": 685591,
  "purge_seq": 0,
  "compact_running": false,
  "disk_size": 634187899,
  "data_size": 445454185,
  "instance_start_time": "1420670152481614",
  "disk_format_version": 6,
  "committed_update_seq": 685591
}

A CPU Profile Analysis Report (generated via xprofiler-cpu-profile) provides a breakdown of resource consumption during a profiling session. It is used to identify performance bottlenecks in application code, third-party NPM packages, or Node.js core modules.

Key sections include:

• Profile Information: Metadata about the session (duration, sample count, total nodes).
• CPU Time Distribution: A breakdown of time spent in Idle, Program, GC (Garbage Collection), and Active/User modes.
• Top 30 Functions by Self Time: Identifies specific functions consuming the most CPU time.
• Top 30 Files/Modules by CPU Time: Identifies which files or modules are responsible for the most CPU load.
• CPU Time by Category: Aggregates time into high-level buckets: NPM Packages, Native/V8, Node.js Core, and Application Code.
• Application Code Hotspots: Specifically highlights functions within the user's own application code that are consuming significant resources.

The project follows a layered architecture inspired by Domain-Driven Design (DDD). The layers are organized as follows:

• app/port/controller (Port Layer): HTTP controllers that handle incoming requests. They inherit from AbstractController and MiddlewareController.
• app/core (Core Layer): Contains the business logic.
  • entity: Core models implementing business behavior.
  • service: Core business logic (e.g., PackageManagerService).
  • event: Asynchronous event definitions and consumers.
• app/repository (Repository Layer): Handles data persistence.
  • model: ORM models (data definitions).
  • XXXRepository: Interfaces for storage and querying.
• app/common (Common Layer): Shared utilities and external service adapters.
• app/infra (Infrastructure Layer): Real implementations of adapters (e.g., NFSClientAdapter, AuthAdapter) tailored for specific PaaS environments.

cnpmcore uses a hierarchical permission model: Organization (Org) $\rightarrow$ Team $\rightarrow$ Package.

• Org: Corresponds to an npm scope (e.g., mycompany $\rightarrow$ @mycompany).
• OrgMember: Users in an Org with roles owner (can manage the Org) or member.
• Team: A permission unit within an Org. Every Org automatically includes a default developers team.
• TeamMember: Users within a Team with roles owner (can manage the Team) or member (can only read authorized packages).
• TeamPackage: Represents the read authorization granted to a Team for a specific package.

This model extends the standard npm model by adding roles to Team members, allowing Team Owners to manage their own teams without needing full Organization Owner permissions.

| Concept | Description |
| :--- | :--- |
| **Org** | Organization, corresponds to a scope (e.g. org `mycompany` $\rightarrow$ `@mycompany`) |
| **OrgMember** | Organization member, role is `owner` (manageable) or `member` |
| **Team** | Permission unit. Each Org automatically creates a `developers` default team |
| **TeamMember** | Team member, role is `owner` (can manage team) or `member` |
| **TeamPackage** | Team's read authorization for a package |

Admin or Org Owners can manage members within an organization. When a new member is added, they are automatically added to the Org's default developers team.

Add a Member

• npm CLI: npm org set <orgName> <username> [role]
• HTTP: PUT /-/org/:orgName/member with a JSON body {"user": "<username>", "role": "<role>"}.

Remove a Member

• npm CLI: npm org rm <orgName> <username>
• HTTP: DELETE /-/org/:orgName/member/<username>.
• Note: Removing a member from an Org automatically removes them from all teams within that Org.

View Members

• npm CLI: npm org ls <orgName> (returns a list of usernames).
• HTTP: GET /-/org/:orgName/member (returns an object mapping usernames to roles, e.g., {"alice": "owner"}).

View User's Teams

Use GET /-/org/:orgName/member/:username/team to see which teams a specific user belongs to.

# Add member via npm CLI
npm org set mycompany alice --registry=http://localhost:7001

# Add member via HTTP
curl -X PUT http://localhost:7001/-/org/mycompany/member \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"user": "alice", "role": "member"}'

# Remove member via npm CLI
npm org rm mycompany alice --registry=http://localhost:7001

# View user's teams
curl http://localhost:7001/-/org/mycompany/member/alice/team \
  -H "Authorization: Bearer <token>"
# Returns: [{"name": "developers", "description": "...", "role": "owner"}, ...]

Administrators or Org Owners can manage organization membership and lifecycle.

Create an Organization

Use a PUT request to the /-/org endpoint.

Delete an Organization

Use a DELETE request to /-/org/:orgName. Warning: This performs a cascade delete of all teams, members, and package grants within that Org.

Manage Members

• Add Member: Use npm org set <org> <user> or a PUT request to /-/org/:orgName/member. New members are automatically added to the developers team.
• Remove Member: Use npm org rm <org> <user> or a DELETE request to /-/org/:orgName/member/:username. This also removes them from all teams in the Org.
• List Members: Use npm org ls <org> or a GET request to /-/org/:orgName/member.

# Create Org
curl -X PUT http://localhost:7001/-/org \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "mycompany", "description": "My Company"}'

# Add Member (npm CLI)
npm org set mycompany alice --registry=http://localhost:7001