@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

Name	Type	Description
§project	`Project`	The project to update
§dependent	`string`	Name 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

Name	Type	Description
§options	`CreateProjectOptions`	Project 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: { config: WorkspaceConfig; dependencyGraph: ReadonlyMap<string, unknown>; projects: ReadonlyMap<string, Project>; reverseDependencyGraph: ReadonlyMap<string, unknown>; root: string; type: WorkspaceType }): Workspace

Creates a new workspace object.

Parameters

Name	Type	Description
§options	`{ config: WorkspaceConfig; dependencyGraph: ReadonlyMap<string, unknown>; projects: ReadonlyMap<string, Project>; reverseDependencyGraph: ReadonlyMap<string, unknown>; root: string; type: WorkspaceType }`	Workspace 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

Name	Type	Description
§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

Name	Type	Description
§workspace	`Workspace`	Workspace containing the dependency graph
§projectA	`string`	Name of the potentially dependent project
§projectB	`string`	Name 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

Name	Type	Description
§workspace	`Workspace`	Workspace containing the dependency graph
§projectName	`string`	Identifier 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

Name	Type	Description
§project	`Project`	Project 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

Name	Type	Description
§project	`Project`	Project 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

Name	Type	Description
§workspace	`Workspace`	Workspace containing the dependency graph
§projectName	`string`	Name 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

Name	Type	Description
§workspace	`Workspace`	Workspace to search in
§projectName	`string`	Identifier 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

Name	Type	Description
§workspace	`Workspace`	Workspace 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

Name	Type	Description
§workspace	`Workspace`	Workspace 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

Name	Type	Description
§project	`Project`	The 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

Name	Type	Description
§project	`Project`	The 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

Name	Type	Description
§project	`Project`	The 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

Name	Type	Description
§workspace	`Workspace`	Workspace to search in
§projectName	`string`	Identifier 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

Name	Type	Description
§project	`Project`	The 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

Name	Type	Description
§project	`Project`	The 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

Name	Type	Description
§project	`Project`	The project to update
§dependents	`unknown`	New 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?:string—

Absolute path to CHANGELOG.md

§internalDependencies?:unknown—

Names of workspace packages this project depends on

§internalDependents?:unknown—

Names of workspace packages that depend on this project

§name:string—

Package name

§packageJson:PackageJson—

Parsed package.json content

§packageJsonPath:string—

Absolute path to package.json

§path:string—

Absolute path to project root

§version:string—

Package version

§interface

Project

A single project within a workspace.

Properties

§readonly changelogPath:string—

Absolute path to CHANGELOG.md (null if not found)

§readonly internalDependencies:unknown—

Names of workspace packages this project depends on

§readonly internalDependents:unknown—

Names of workspace packages that depend on this project

§readonly name:string—

Package name from package.json

§readonly packageJson:PackageJson—

Parsed package.json content

§readonly packageJsonPath:string—

Absolute path to package.json

§readonly path:string—

Absolute path to project root directory

§readonly private:boolean—

Whether this is a private package

§readonly publishable:boolean—

Whether this is a publishable package

§readonly version:string—

Package version from package.json

§interface

Workspace

Complete workspace representation. Contains all discovered projects and their relationships.

Properties

§readonly config:WorkspaceConfig—

Configuration used for discovery

§readonly dependencyGraph:ReadonlyMap<string, unknown>—

Dependency graph (project name -> dependents)

§readonly projectList:unknown—

Projects 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:string—

Absolute path to workspace root

§readonly type:WorkspaceType—

Detected workspace type

§interface

WorkspaceConfig

Workspace configuration options.

Properties

§readonly exclude:unknown—

Patterns to exclude from discovery

§readonly includeChangelogs:boolean—

Whether to include changelog paths in discovery

§readonly patterns:unknown—

Glob patterns for finding packages

§readonly trackDependencies:boolean—

Whether to track internal dependencies

◆ Types

§type

WorkspaceType

Workspace type indicating the package manager / tool in use.

● Variables

§type

DEFAULT_EXCLUDE

Default exclusion patterns.

§type

DEFAULT_PATTERNS

Default workspace discovery patterns.

§type

DEFAULT_WORKSPACE_CONFIG

Default workspace configuration.