TyphonJS•2y ago

Release `TRL 0.1.0` - The journey to beta begins...

Greets @FVTT ▹ Developer, I am very excited to announce the release of TRL 0.1.0. This is a major release and begins the path toward a full "beta" launch. WARNING: This is a major breaking change release. Some of your cheese has been moved, but it is not gone. Now don't get too scared as this is not a change in the functional aspects of TRL, but a significant refinement to the API structure and locations of where various resources are located. This was necessary for API doc coherency and to move resources around in the library construction to aid future progress. WARNING: If you are currently actively working on a new release or project with a previous TRL release it is recommended that you finish your current working effort before upgrading. There is no rush. A ton of work has gone into the tooling used behind the scene that generates TRL. Full TS declarations for ESM packages are now shipped and API docs! Not just API docs, but fully cross-linked API docs between runtime & standard -> Svelte - > Foundry VTT docs -> to a complete linking of the modern web (TS lib docs). To be honest I don't think I've seen any library / project documentation that achieves this level of total coverage. You can find the API docs here: https://typhonjs-fvtt-lib.github.io/api-docs/ Use the API doc search feature to find the class / function you need to update regarding import location. You will now begin to understand the scope and size of TRL as there likely are many resources that you have yet to utilize in your package development. Several new resources were added for TRL 0.1.0. Svelte v4 is required as well as upgrading to Vite 4.3+. When you upgrade your repos simply raise all package dependencies to the max available. The demo repos are updated as well. You might notice usage of #runtime and #standard in the demo repos. Since Vite 4.2 support has been added for the imports field of package.json. I find it very convenient to shorten the import package name for TRL to #runtime and #standard; it also makes the documentation more pleasant to look at. You can find an example of the setup required for this in the demo repo: https://github.com/typhonjs-fvtt-demo/essential-svelte-esm/blob/main/package.json#L12-L15 Certainly please do raise any concerns and issues and let's discuss how to get you moving forward again. The amount of changes in API import locations was too great to make a detailed list of every instance. However let's start making a list of locations where things come up. For instance TJSGameSettings is available via: import { TJSGameSettings } from '#runtime/svelte/store/fvtt/settings'; For instance TJSDocument is available via: import { TJSDocument } from '#runtime/svelte/store/fvtt/document'; I recorded an example of updating a package to the latest TRL and it's not too bad.. https://www.youtube.com/watch?v=ILLobXsYldI This is the most major restructuring that likely will occur w/ TRL and I made sure to be as comprehensive as possible. I will be making an public overview video later this week that highlights some of the new changes and efforts available in TRL this year.

TyphonJS-FoundryVTT

YouTube

Dev Snapshot - Updating to TRL v0.1.0

Provides an overview example of what it is like to update a TRL package to v0.1.0

15 Replies

chimis•2y ago

I had issues just updating the dependencies in my package.json and running npm install. I was able to update my module with a couple of steps: 1. ran npm cache clean --force 2. deleted my node_modules directory 3. deleted package-lock.json 4. made my dependency version changes and ran npm insall. Just in case that helps someone else, that worked for me.

TyphonJS (Michael)OP•2y ago

Indeed @chimis. Sometimes it's useful to just delete the node_modules directory and package-lock.json file and do a fresh install. @geoidesic I think you may be one of the first larger package efforts (aka a system) to make the move to TRL 0.1.0. If you have the time and have any thoughts on the process you went through I'm sure others would be glad to be reassured that it isn't "too bad". As mentioned in our discussion in another post in general you'll want to input into search feature of the API docs any symbols that are not found when building against TRL 0.1.0. In the attached pict I show a search for TJSDocument as it has a new import path. To make the API and docs more coherent the large majority of changes for TRL 0.1.0 are refinements to the sub-path exports of TRL that are more specific to the logical grouping of the API. ---- There are a couple of changes that group functions together. An example of that is the debounce function is now located in the Timing class from #runtime/util. Do search for the missing symbol in the docs debounce in this case and you'll find it right away. ---- One of the few functional changes to TRL 0.1.0 is for reactive embedded collection creation from TJSDocument. Instead of passing a string name for the embedded collection type you pass the class instance of the document that has a documentName property matching the collection you are targeting. Often that is just removing the " from the creation.

const doc = new TJSDocument(A_FOUNDRY_DOCUMENT);

// Taken from 'essential-svelte-esm'
const wildcard = doc.embedded.create('Item', {
   name: 'wildcard',
   filters: [filterSearch],
   sort: (a, b) => a.name.localeCompare(b.name)
});

const doc = new TJSDocument(A_FOUNDRY_DOCUMENT);

// Taken from 'essential-svelte-esm'
const wildcard = doc.embedded.create('Item', {
   name: 'wildcard',
   filters: [filterSearch],
   sort: (a, b) => a.name.localeCompare(b.name)
});

to the following simply removing the ' around Item in the create call.

const doc = new TJSDocument(A_FOUNDRY_DOCUMENT);

// Taken from 'essential-svelte-esm'
const wildcard = doc.embedded.create(Item, {
   name: 'wildcard',
   filters: [filterSearch],
   sort: (a, b) => a.name.localeCompare(b.name)
});

const doc = new TJSDocument(A_FOUNDRY_DOCUMENT);

// Taken from 'essential-svelte-esm'
const wildcard = doc.embedded.create(Item, {
   name: 'wildcard',
   filters: [filterSearch],
   sort: (a, b) => a.name.localeCompare(b.name)
});

Other than that things should be fairly straight forward and only slightly disruptive when moving to TRL 0.1.0 as it is a process of refining the import statements connecting things to the new sub-path exports of TRL.

TyphonJS (Michael)OP•2y ago

And the pict example to find TJSDocument. The import path changed to #runtime/svelte/store/fvtt/document

Nekro Darkmoon•2y ago

It'll be a while before we move to 0.1.0. We've been working on some big additions to the system so they're taking up all the bandwitdh but other than that we have a lot of TJS imports and other stuff that will need migrating 😄 I have already updated my modules to 0.1.0 and that was relatively smooth

TyphonJS (Michael)OP•2y ago

Oh yeah, it definitely makes sense to make the move when whatever package you are working on is at a stable point; IE you finished whatever current features you are working on and have a stable point to do the upgrade.

geoidesic•2y ago

Yes. Thanks again, Michael, for the support with the upgrade. It took me an hour all told to do the upgrade. The bulk of the work was just altering import paths. The API search feature was very useful for tracking that. - Occasionally the names of things had changed, so I wasn't sure what to search for (e.g. looked for normalizeString but it had changed to just normalize) - Also the search field is illegible on Safari btw It's nothing to be afraid of. Also I'd say that I wasn't entirely sure what was meant by "don't do it till your code-base is stable"... because in my view my code-base is still a ways off from that but I think the way I would interpret that is "don't do the upgrade it in the middle of doing something else". In my case that advice wasn't appropriate because this upgrade was required in order to fix a bug (i.e. support for v11 core drag & drop). And that's also why I was a very early adopter.

TyphonJS (Michael)OP•2y ago

Yeah.. It's always best to just start a refactor / migration when you aren't in the middle of existing development activities. Regarding the normalizeString change. Indeed it's reasonable for folks converting to TRL 0.1.0 to review the "static class" changes for some of the utility functions that were previously available via #runtime/svelte/util. Mainly some hashing, string, and timing functions are grouped under three static classes with those functions now. The static classes are respectively Hashing, Strings, Timing that are now available from #runtime/util. I decided against creating additional sub-path exports where each would just contain a couple of functions, so they are grouped under those static classes. You can find documentation for these utility classes here: https://typhonjs-fvtt-lib.github.io/api-docs/modules/_runtime_util.html

david aka claudekennilol•2y ago

Is the overall plan still to release this as a library mod so that each individual mod doesn't have to include the full library with them? (just curious)

TyphonJS (Michael)OP•2y ago

It is, but likely toward the end of the "beta" lifecycle due to Foundry not having a proper package management system that has versioning on the server / client side. IE multiple versions of the same package installed. The really big space saving goal is to not have to compile the TRL library into each package that ships for Foundry and use import maps to provide TRL by a global CDN (unpkg, etc.) then as a complete fallback release TRL also as a library module for those that need to run Foundry offline. This is an extreme space saving over everyone compiling TRL into their own package when released in a platform direction. I have already done initial experiments on the Foundry library module version, but that will have to come out when TRL is toward the end of "beta". The CDN version is much closer to possibility and will be something I'm looking to get together by the end of the year. Just a FYI too that when you compile your package just what you use is included via ES Modules / treeshaking. Some articles on import maps: https://web.dev/import-maps-in-all-modern-browsers/ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap

Nekro Darkmoon•17mo ago

This change needs to be documented 😄

Nekro Darkmoon•17mo ago

I also can't find documentation for stuff like ApplicationShell same with TJSMenu, TJSToggleIconButton, etc. it seems like #standard/component didn't make it into the api 🤔

TyphonJS (Michael)OP•17mo ago

The Svelte components don't have TS declarations yet hence no documentation. By the end of the year when I start to get things oriented towards SvelteKit and the tooling in SvelteKit to package up component libraries and create declarations then it will be possible to add them to the documentation. The API docs are produced from the TS declarations. Presently just all of the ESM library code has declarations and docs.

Nekro Darkmoon•17mo ago

👌

TyphonJS (Michael)OP•17mo ago

And yeah.. There will be some changes at times with the standard library where things may get shuffled around. Not so much the components, but some of the supporting ESM code. IE it may get promoted to the core TRL library like in the case of createFilterQuery. It's a helper function and certainly useful to look at that block of code when it comes to creating a filter function that also is a store. There definitely may be cases when you need to build filter and sort functions for dynamic reducers that don't have an equivalent existing helper function to build them. Also createFilterQuery is just the first of possibly many stock helper functions.

Nekro Darkmoon•17mo ago

👍

Gaming

Programming

Release `TRL 0.1.0` - The journey to beta begins...