feat(core): export several util functions

[sehilyi]

Fix #983

Change List

• Added several util functions for calculating chromosome positions. This is the first time exposing util functions, and the user API could be changed after discussing with the team.

import { utils } from 'gosling.js';
console.log(utils);
// print
{
getRelativeGenomicPosition,
computeChromSizes,
getChromInterval,
getChromTotalSize,
parseGenomicPosition,
sanitizeChrName
}

import { getRelativeGenomicPosition } from 'gosling.js/utils';

Checklist

• Ensure the PR works with all demos on the online editor
• Unit tests added or updated
• Examples added or updated
• Documentation updated (e.g., added API functions)
• Screenshots for visual changes (e.g., new encoding support or UI change on Editor)

[sehilyi]

@manzt Could you review this to see if this makes sense to you? Open to any suggestions regarding how we want to expose utility functions to users.

[manzt]

Looks fine to me. Although I wonder about exporting these under a namespace like _interval for now. What's the plan in versioning Gosling with relation to these utilities going forward? A namespace like _internal or _util might suggest to most users "use with caution" or carry other semantics compared to the rendering logic.

import { _internal } from "gosling.js";

const { getRelativeGenomicPosition } = _internal;

I think ideally we'd have a separate library for these shared utilities in a monorepo (e.g., @gosling-lang/utils) which could be versioned separately from gosling as a whole. That way folks could have that versioned separately. However, in the short term this seems to be a fine solution.

[sehilyi]

Although I wonder about exporting these under a namespace like _interval for now. What's the plan in versioning Gosling with relation to these utilities going forward? A namespace like _internal or _util might suggest to most users "use with caution" or carry other semantics compared to the rendering logic.

@manzt Given that the code has been changed after I merged your update, would you suggest adding _ to all functions? e.g.,

export {
    getRelativeGenomicPosition as _getRelativeGenomicPosition,
    computeChromSizes as _computeChromSizes,
    getChromInterval as _getChromInterval,
    getChromTotalSize as _getChromTotalSize,
    parseGenomicPosition as _parseGenomicPosition
} from './core/utils/assembly';
export { sanitizeChrName as _sanitizeChrName } from './data-fetchers/utils';

I think we want to support the utils functions as a separate library in the future (@gosling-lang/utils), but we have not decided what functions (and in what names) we want to expose to users.

[manzt]

@manzt Given that the code has been changed after I merged your update, would you suggest adding _ to all functions?

I think it's fine as is (no _). Right now we can say that gosling.js/utils is versioned with gosling.js, and we could make breaking changes to these utilities in minor version changes. In the future, we will hopefully have a separate package with utilities. However, I'd only put uilities that are used across other sub-packages in @gosling-lang/utils, or ones that we want to make avaiablie to end users (like this one).

We should keep utilities which are only used by a given package (e.g., @gosling-lang/core) within that package, unless they are used elsewhere or intended as a part of some public API for end users.

Utilities can be "promoted" to this package if they end up used across projects or by end users, but this "promotion" should come with a consideration of the API and process of making it public.