@hyperfrontend/versioning/workspace/models

models

Workspace data models: projects, workspace config, and project-level query helpers.

Project is the per-package shape (name, version, path, dependencies, declared changelog) carried throughout the workspace operations; createProject is the factory. Workspace, WorkspaceConfig, and WorkspaceType describe the workspace as a whole. The project-level predicates (isPublishable, isPrivate, hasChangelog, hasInternalDependencies, hasInternalDependents) and accessors (getDependencyCount) cover the common questions consumers ask of a Project without reaching into its raw fields.

API Reference§

ƒ Functions

§function

addDependent(project: Project, dependent: string): Project

Creates a copy of a project with an added internal dependent.
Parameters
NameTypeDescription
§project
ProjectThe project to update
§dependent
stringName of the dependent to add
Returns
Project
A new Project with the added dependent
Example

Add an internal dependent to a project

import { discoverProject, addDependent } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project) {
  const updated = addDependent(project, '@myorg/new-app')
  console.log('Dependents now:', updated.internalDependents)
}
§function

createProject(options: CreateProjectOptions): Project

Creates a new Project object.
Parameters
NameTypeDescription
§options
CreateProjectOptionsProject properties
Returns
Project
A new Project object
Example

Create a new Project object

import { createProject, readPackageJson } from '@hyperfrontend/versioning'

const packageJson = readPackageJson('./libs/my-lib/package.json')
const project = createProject({
  name: '@myorg/my-lib',
  version: '1.0.0',
  path: './libs/my-lib',
  packageJsonPath: './libs/my-lib/package.json',
  packageJson,
  changelogPath: './libs/my-lib/CHANGELOG.md',
})
§function

createWorkspace(options: CreateWorkspaceOptions): Workspace

Creates a new workspace object.
Parameters
NameTypeDescription
§options
CreateWorkspaceOptionsWorkspace properties
Returns
Workspace
A new Workspace object
Example

Create a new workspace object

import { createWorkspace, createWorkspaceConfig, createProject } from '@hyperfrontend/versioning'

const projects = new Map([['@myorg/utils', createProject({ ... })]])
const workspace = createWorkspace({
  root: '/path/to/workspace',
  type: 'nx',
  projects,
  config: createWorkspaceConfig(),
  dependencyGraph: new Map(),
  reverseDependencyGraph: new Map(),
})
§function

createWorkspaceConfig(options?: Partial<WorkspaceConfig>): WorkspaceConfig

Creates a new workspace configuration by merging with defaults.
Parameters
NameTypeDescription
§options?
Partial<WorkspaceConfig>Partial configuration options
Returns
WorkspaceConfig
Complete workspace configuration
Example

Create a workspace configuration with defaults

import { createWorkspaceConfig } from '@hyperfrontend/versioning'

const config = createWorkspaceConfig({
  patterns: ['packages/*', 'libs/*'],
  exclude: ['node_modules', 'dist'],
})
§function

dependsOn(workspace: Workspace, projectA: string, projectB: string): boolean

Checks if projectA depends on projectB.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace containing the dependency graph
§projectA
stringName of the potentially dependent project
§projectB
stringName of the potential dependency
Returns
boolean
True if projectA depends on projectB
Example

Check if one project depends on another

import { discoverWorkspace, dependsOn } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
if (dependsOn(workspace, '@myorg/app', '@myorg/utils')) {
  console.log('@myorg/app directly depends on @myorg/utils')
}
§function

getDependencies(workspace: Workspace, projectName: string): unknown

Gets projects that the given project depends on.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace containing the dependency graph
§projectName
stringIdentifier of the project to look up
Returns
unknown
Array of dependency project names
Example

Get projects that the given project depends on

import { discoverWorkspace, getDependencies } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
const deps = getDependencies(workspace, '@myorg/app')
console.log(`@myorg/app depends on:`, deps)
§function

getDependencyCount(project: Project): number

Gets the dependency count (internal dependencies).
Parameters
NameTypeDescription
§project
ProjectProject instance to analyze
Returns
number
Number of internal dependencies
Example

Get the dependency count for a project

import { discoverProject, getDependencyCount } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/my-lib')
if (project) {
  console.log(`${project.name} depends on ${getDependencyCount(project)} internal packages`)
}
§function

getDependentCount(project: Project): number

Gets the dependent count (packages that depend on this one).
Parameters
NameTypeDescription
§project
ProjectProject instance to analyze
Returns
number
Number of internal dependents
Example

Get the dependent count for a project

import { discoverProject, getDependentCount } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project) {
  console.log(`${project.name} is used by ${getDependentCount(project)} packages`)
}
§function

getDependents(workspace: Workspace, projectName: string): unknown

Gets projects that depend on the given project.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace containing the dependency graph
§projectName
stringName of the dependency
Returns
unknown
Array of dependent project names
Example

Get projects that depend on a given project

import { discoverWorkspace, getDependents } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
const dependents = getDependents(workspace, '@myorg/utils')
console.log(`Packages depending on @myorg/utils:`, dependents)
§function

getProject(workspace: Workspace, projectName: string): Project

Gets a project by name from the workspace.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace to search in
§projectName
stringIdentifier of the project to retrieve
Returns
Project
The project or undefined if not found
Example

Get a project by name from the workspace

import { discoverWorkspace, getProject } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
const project = getProject(workspace, '@myorg/utils')
if (project) {
  console.log(`Version: ${project.version}`)
}
§function

getProjectCount(workspace: Workspace): number

Gets the count of projects in the workspace.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace to count projects in
Returns
number
Number of projects
Example

Get the count of projects in the workspace

import { discoverWorkspace, getProjectCount } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
console.log(`Workspace contains ${getProjectCount(workspace)} projects`)
§function

getProjectNames(workspace: Workspace): unknown

Gets all project names in the workspace.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace to retrieve project names from
Returns
unknown
Array of project names
Example

Get all project names in the workspace

import { discoverWorkspace, getProjectNames } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
const names = getProjectNames(workspace)
console.log(`Found ${names.length} projects:`, names)
§function

hasProjectChangelog(project: Project): boolean

Checks if a project has a changelog file.
Parameters
NameTypeDescription
§project
ProjectThe project to check
Returns
boolean
True if changelog exists
Example

Check if a project has a changelog

import { discoverProject, hasChangelog } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/my-lib')
if (project && !hasChangelog(project)) {
  console.log('Warning: No changelog found for', project.name)
}
§function

hasInternalDependencies(project: Project): boolean

Checks if a project has any internal dependencies.
Parameters
NameTypeDescription
§project
ProjectThe project to check
Returns
boolean
True if project depends on other workspace packages
Example

Check if a project has internal dependencies

import { discoverProject, hasInternalDependencies } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/my-lib')
if (project && hasInternalDependencies(project)) {
  console.log(`${project.name} depends on:`, project.internalDependencies)
}
§function

hasInternalDependents(project: Project): boolean

Checks if a project has any internal dependents.
Parameters
NameTypeDescription
§project
ProjectThe project to check
Returns
boolean
True if other workspace packages depend on this project
Example

Check if a project has internal dependents

import { discoverProject, hasInternalDependents } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project && hasInternalDependents(project)) {
  console.log(`${project.name} is used by:`, project.internalDependents)
}
§function

hasProject(workspace: Workspace, projectName: string): boolean

Checks if a project exists in the workspace.
Parameters
NameTypeDescription
§workspace
WorkspaceWorkspace to search in
§projectName
stringIdentifier of the project to check
Returns
boolean
True if the project exists
Example

Check if a project exists in the workspace

import { discoverWorkspace, hasProject } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
if (hasProject(workspace, '@myorg/utils')) {
  console.log('Package exists in workspace')
}
§function

isPrivate(project: Project): boolean

Checks if a project is private.
Parameters
NameTypeDescription
§project
ProjectThe project to check
Returns
boolean
True if the project is marked as private
Example

Check if a project is private

import { discoverProject, isPrivate } from '@hyperfrontend/versioning'

const project = discoverProject('./apps/internal-app')
if (project && isPrivate(project)) {
  console.log('Skipping private package')
}
§function

isPublishable(project: Project): boolean

Checks if a project is publishable (public and has name/version).
Parameters
NameTypeDescription
§project
ProjectThe project to check
Returns
boolean
True if the project can be published
Example

Check if a project is publishable

import { discoverProject, isPublishable } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/my-lib')
if (project && isPublishable(project)) {
  console.log(`${project.name} can be published to npm`)
}
§function

withDependents(project: Project, dependents: unknown): Project

Creates a copy of a project with updated internal dependents.
Parameters
NameTypeDescription
§project
ProjectThe project to update
§dependents
unknownNew list of internal dependents
Returns
Project
A new Project with updated dependents
Example

Create a project copy with updated dependents

import { discoverProject, withDependents } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project) {
  const updated = withDependents(project, ['@myorg/app', '@myorg/web'])
  console.log('Updated dependents:', updated.internalDependents)
}

◈ Interfaces

§interface

CreateProjectOptions

Options for creating a project.
Properties
§changelogPath?:stringAbsolute path to CHANGELOG.md
§internalDependencies?:unknownNames of workspace packages this project depends on
§internalDependents?:unknownNames of workspace packages that depend on this project
§name:stringPackage name
§packageJson:PackageJsonParsed package.json content
§packageJsonPath:stringAbsolute path to package.json
§path:stringAbsolute path to project root
§version:stringPackage version
§interface

Project

A single project within a workspace.
Properties
§readonly changelogPath:stringAbsolute path to CHANGELOG.md (null if not found)
§readonly internalDependencies:unknownNames of workspace packages this project depends on
§readonly internalDependents:unknownNames of workspace packages that depend on this project
§readonly name:stringPackage name from package.json
§readonly packageJson:PackageJsonParsed package.json content
§readonly packageJsonPath:stringAbsolute path to package.json
§readonly path:stringAbsolute path to project root directory
§readonly private:booleanWhether this is a private package
§readonly publishable:booleanWhether this is a publishable package
§readonly version:stringPackage version from package.json
§interface

Workspace

Complete workspace representation. Contains all discovered projects and their relationships.
Properties
§readonly config:WorkspaceConfigConfiguration used for discovery
§readonly dependencyGraph:ReadonlyMap<string, unknown>Dependency graph (project name -> dependents)
§readonly projectList:unknownProjects ordered by name
§readonly projects:ReadonlyMap<string, Project>All discovered projects indexed by name
§readonly reverseDependencyGraph:ReadonlyMap<string, unknown>Reverse dependency graph (project name -> dependencies)
§readonly root:stringAbsolute path to workspace root
§readonly type:WorkspaceTypeDetected workspace type
§interface

WorkspaceConfig

Workspace configuration options.
Properties
§readonly exclude:unknownPatterns to exclude from discovery
§readonly includeChangelogs:booleanWhether to include changelog paths in discovery
§readonly patterns:unknownGlob patterns for finding packages
§readonly trackDependencies:booleanWhether to track internal dependencies

◆ Types

§type

WorkspaceType

Workspace type indicating the package manager / tool in use.
type WorkspaceType = "nx" | "turbo" | "lerna" | "pnpm" | "npm" | "yarn" | "rush" | "unknown"

● Variables

§type

DEFAULT_EXCLUDE

Default exclusion patterns.
§type

DEFAULT_PATTERNS

Default workspace discovery patterns.
§type

DEFAULT_WORKSPACE_CONFIG

Default workspace configuration.