Any requests for API-breaking changes

[khaledhosny]

I’m planning to make a first v2.x release soon with all the API-breaking changes, so if anyone has any other requests for more API-breaking changes, now is a good time to request them. We are unlikely to get any such breaking changes again in a long time.

[khaledhosny]

@akash-joshi @chearon @ghostdevv @graphicore @justvanrossum @lianghai @simoncozens @tomasdev

[tomasdev]

I haven't used hbjs in a while. I use harfrust now, and only expose to JS the things I need.

[lianghai]

Nothing off the top of my head, but I’ll think about this.

At this point, mostly I’m interested in closely reviewing the eventual distribution (see also the current one https://www.npmjs.com/package/harfbuzzjs?activeTab=code), in order to make sure a minimal, well understood set of files and API surface are exposed. Will you be creating pre-releases in https://github.com/harfbuzz/harfbuzzjs/releases for review?

Btw, for such a small project, using both “Issues” and “Discussions” is kinda confusing… Big projects benefit from this because they need to have multiple levels of triaging, typically from “Discussions” to “Issues” to “Pull requests”.

[khaledhosny]

https://github.com/harfbuzz/harfbuzzjs/releases/tag/v1.0.0-beta.1

[lianghai]

Smoothly migrated the Unicode core specification (a private repo)’s usage of harfbuzzjs to beta 1. Sharing some diffs below.

As expected, the workaround for Vite (as of 7.3.2, its problem with the exported promise persists) isn’t needed anymore:

I also want to show how this well-typed API also gets rid of those inline comments, because now the first-party documentation is just a hover away:

[khaledhosny]

Excellent!

[khaledhosny]

I published a second beta https://github.com/harfbuzz/harfbuzzjs/releases/tag/v1.0.0-beta.2 (also on npm) so others can test the changes since the previous beta.

[lianghai]

Working as expected!

[akash-joshi]

Since this is a breaking release, it would be really valuable to have a changelog or migration guide (e.g. MIGRATING.md) documenting all the changes from 1.x to 2.x.

Even a simple list of what changed and why would go a long way. The bigger question is - where do we release this 😅? With the V2 release?

[khaledhosny]

Yes, I was planning something like this. Waiting until the final shape of the API is clear.

[khaledhosny]

• Add v1 migration guide #188

[justvanrossum]

Can (did?) we get rid of the explicit hb = await harfbuzz; and do plain ES6 imports?

I assume the recent changes make it possible for webpack to pick up the .wasm file automatically?

[lianghai]

Oh yeah good point! I forgot about this.

Currently how the package’s default export is a Promise is quite strange. It feels the package should either export an already fulfilled instance (using top-level await?), or (especially to avoid the potentially unnecessary eager initiation) only export an async function for initiation.

[khaledhosny]

How about this #184?

[lianghai]

Do people feel it’s worth the trouble to switch the casing of Json and Svg in various names to JSON and SVG, following the JS/Web convention (eg, URL.toJSON and SVGElement)?

harfbuzzjs/src/font.ts

Line 335 in abcd821

glyphToJson(glyphId: number): SvgPathCommand[] {

harfbuzzjs/src/types.ts

Line 50 in abcd821

export interface SvgPathCommand {

I almost started working on a PR, but then realized there’s also a lot of Id, Ids, Ui…

[khaledhosny]

I have no strong opinion (I slightly prefer less API churn), but I agree, if we do this we do it thoroughly. Waiting on others opinions for this.

[khaledhosny]

This is the remaining open issue, before making a final v1.0.0 release. Can others voice their opinion with or against this change?

[chearon]

I prefer treating acronyms as words, Svg and Json, even though it contradicts most web APIs. It could really go either way...

[khaledhosny]

Since this means no change, I’m leaning towards this as well.

[lianghai]

There seems to be some confusion about the usage of undefined and null in JS, and TS’s syntax of optional parameters:

• undefined: https://github.com/search?q=repo%3Aharfbuzz%2Fharfbuzzjs+%22undefined%22&type=code
• null: https://github.com/search?q=repo%3Aharfbuzz%2Fharfbuzzjs+%22null%22&type=code
• ?: https://github.com/search?q=repo%3Aharfbuzz%2Fharfbuzzjs%20%22%3F%3A%22&type=code

For example, this overloading doesn’t seem necessary:

harfbuzzjs/src/buffer.ts

Lines 73 to 76 in abcd821

	constructor();
	/** @internal Wrap an existing buffer pointer. */
	constructor(existingPtr: number);
	constructor(existingPtr?: number) {

And here font?: Font | null means font: Font | null | undefined = undefined (because foo?: T is equivalent to foo: T | undefined = undefined), which doesn’t feel intentional:

Note that for JS (runtime), all parameters are optional (T | undefined), but TS assumes non-optional (T) by default in order to simplify the handling of types. foo?: T (equivalent to foo: T | undefined = undefined) means this parameter can be omitted, while foo: T | undefined means this parameter can take an explicit undefined value but it can’t be omitted.

harfbuzzjs/src/buffer.ts

Lines 376 to 382 in abcd821

	serialize(
	font?: Font | null,
	start: number = 0,
	end?: number | null,
	format: BufferSerializeFormat = BufferSerializeFormat.TEXT,
	flags: number = 0,
	): string {

Indeed, how to use undefined vs null is indeed one of the biggest sources of confusion in JS (I constantly struggle to decide to use undefined or null), and TS’s syntax of optional parameter kind of makes it worse. But in general, it doesn’t help to have optional parameters before required parameters.

[khaledhosny]

I’m as clueless about this as it gets. I don’t even understand the difference between null and undefined and why JS have both. I feel like I should just ignore null and go with undefined everywhere?

[tomasdev]

They indicate different things: one is "lack of presence" (undefined) and one is "present but with no value" (null)

foo(arg: Font | null) and foo(arg?: Font) are different because the first one requires arg to be passed explicitly like foo(null), whereas the second one makes it optional, thus making foo() valid.

There are too many nuances historically on the differences of the two, but ideally undefined is better, because it also allows chaining obj?.prop?.nested for example.

[khaledhosny]

Thanks. I unified things to use undefined:

• Replace null with undefined throughout the API #200

[lianghai]

Yeah, I agree that when there’s no intention to clearly distinguish undefined and null in an API design, it’s easier to stick to undefined, especially because you can’t escape from undefined in JS (it appears everywhere) so you already have to deal with it anyway.

The prevalence of undefined has to do with JS’s design that [][0] and {}["foo"] both get you undefined instead of some index error, thus they’re kinda equivalent to [undefined][0] and { foo: undefined }["foo"].

…, because it also allows chaining obj?.prop?.nested for example.

To be clear, optional chaining does accept both undefined and null, but it only evaluates to undefined (another sign that undefined is more neutral and default than null) so it’s easier if your API expects undefined instead of null.

[lianghai]

Fyi, this is another good reason to avoid null: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof#typeof_null. Only learned about this because I ran into it today in my own project…

[khaledhosny]

If there are no objections, I’m going to make a final v1.0.0 in the next few days.

[khaledhosny]

https://github.com/harfbuzz/harfbuzzjs/releases/tag/v1.0.0

Thanks everyone for your input.

[lianghai]

Amazing! Thank you for all the work! There’s an extra “`” at the end of the Buffer.serialize() line.

[khaledhosny]

Fixed, thanks!