feat: scaffold api, commands, and tests#2
Conversation
onehumandev
force-pushed
the
onehumandev/api-entry
branch
2 times, most recently
from
4477b6a to
2adebbf
Compare
onehumandev
force-pushed
the
onehumandev/api-entry
branch
4 times, most recently
from
95c03bb to
b936ce3
Compare
There was a problem hiding this comment.
The PR description doesn't mention the design discussion in tauri-apps/tauri#12276 — I think it'd be worth linking, since that comment is the broader design context for this plugin.
Reading the proposal alongside this PR:
- Platform-specific entry points with 1:1 parity to each OS's native APIs ✓
- A cross-platform overlay on top (PathMapping) rather than being the only option ✓
- Coexistence of both fine-grained and convenience APIs ✓
Noted a few places where the shape diverges:
-
Enum arguments instead of named methods. Proposal:
IosPaths.appLibrary(). This PR:resolveApplePath(ApplePath.LibraryDirectory). -
iOS and macOS are merged into
ApplePath. The proposal has a dedicatedIosPaths. The PR'sApplePathenum covers allSearchPathDirectoryvariants, several of which are macOS-only. Is the plan to split this into per-OS enums later, or to validate at theresolve_apple_pathboundary? -
Windows is more granular than proposed. The PR's WindowsPath = {win32} | {winMsix} tagged union captures the MSI/MSIX distinction that the proposal collapsed into a single
WindowsPaths. I think that's an improvement on the proposal, but it's worth calling out as a deliberate divergence so the upstream maintainers can react to it. -
Surface is much wider than "common cases". The proposal says: "simplified path for common cases via the cross-platform API, and fine-grained control when platform-specific behavior matters."
Curious whether these divergences are deliberate or things we plan to address in follow-up PRs? Just wanted to call out for discussion. Thanks!
onehumandev
force-pushed
the
onehumandev/api-entry
branch
2 times, most recently
from
ec5166b to
be1055c
Compare
Scaffolds the Rust and TS API contracts for path resolution, including: 1. Tauri commands 1. Typescript bindings 1. Rust wiring for commands, pending implementation The paths for each platforms are strongly typed as enums in both TS and Rust, based on the APIs available natively for each platform. iOS and Mac are based on SearchPathDirectory, Android on what is available to the Context class, Win32 paths (for MSI installations) on KNOWNFOLDERID, and AppData (MSIX) paths based on ApplicationData. These paths can be accessed with platform-specific methods for resolving the path and passing in the enum for the requested path. To allow users to not need to write their own platform branching logic, we also have the PathMapping object. This allows the user to define the path for each supported platform, and calling `resolve()` will retrieve the path based on the callers OS. We allow the user to have access to both the convenience of PathMapping, and to the direct methods that resolve the path. We do not make any decisions about which paths are available for a platform; this is a one-to-one matching to what each OS provides. Even if a path seems to be one that would not be of interest for a Tauri app, we still include it. This implementation is based on the discussion here: tauri-apps/tauri#12276 There are some implementation differences in this API compared to what was originally suggested in the above issue, listed below: 1) Enum arguments instead of named methods. Proposal: IosPaths.appLibrary(). This PR: resolveApplePath(ApplePath.LibraryDirectory). By using enum values instead of one method per path, the surface area of the API is vastly smaller. We now only have 6 methods (one per platform, plus one more for Android path collections) instead of one method per path. This makes the API much more ergonomic and easier to maintain. 2) Windows is more granular than proposed. The PR's WindowsPath = {win32} | {winMsix} tagged union captures the MSI/MSIX distinction that the proposal collapsed into a single WindowsPaths. This allows for the dev to clearly state which packaging they plan to ship. There is not a known use case where an app will need to be built for both MSIX and MSI (as opposed to iOS and Mac, where it is very common for an app to be created for both). With this pattern, when resolving a path, the dev doesn't have to verbosely differentiate between which path they want for their Windows package. 3) Surface is much wider than "common cases". The proposal says: "simplified path for common cases via the cross-platform API, and fine-grained control when platform-specific behavior matters." Since the actual path resolution is not made more complicated by how many paths we expose, there is no benefit to limiting which paths are allowed. Instead, by simply reflecting exactly what each platforms API provides, we give the client full control with no opinion forced on them. As long as the single low-level invocation to resolve a path works, all other paths will work without issue.
onehumandev
force-pushed
the
onehumandev/api-entry
branch
from
be1055c to
bdcf289
Compare
Good points on all the above; PR description has been updated with the above points, and we also now include an API to cover Linux. |
4 participants
Scaffolds the Rust and TS API contracts for path resolution, including:
The paths for each platforms are strongly typed as enums in both TS and Rust,
based on the APIs available natively for each platform.
iOS and Mac are based on SearchPathDirectory, Android on what is available to the Context
class, Linux on the XDG spec, Win32 paths (for MSI installations) on KNOWNFOLDERID, and AppData (MSIX) paths
based on ApplicationData.
These paths can be accessed with platform-specific methods for resolving the path and
passing in the enum for the requested path.
To allow users to not need to write their own platform branching logic, we also have
the PathMapping object.
This allows the user to define the path for each supported platform, and calling
resolve()will retrieve the path based on the callers OS.We allow the user to have access to both the convenience of PathMapping, and to the
direct methods that resolve the path.
We do not make any decisions about which paths are available for a platform; this is a
one-to-one matching to what each OS provides.
Even if a path seems to be one that would not be of interest for a Tauri app, we still
include it.
This implementation is based on the discussion here:
tauri-apps/tauri#12276
There are some implementation differences in this API compared to what was originally
suggested in the above issue, listed below:
Enum arguments instead of named methods. Proposal: IosPaths.appLibrary(). This PR:
resolveApplePath(ApplePath.LibraryDirectory).
By using enum values instead of one method per path, the surface area of the API is
vastly smaller. We now only have 6 methods (one per platform, plus one more for Android
path collections) instead of one method per path.
This makes the API much more ergonomic and easier to maintain.
Windows is more granular than proposed. The PR's WindowsPath = {win32} | {winMsix}
tagged union captures the MSI/MSIX distinction that the proposal collapsed into a single
WindowsPaths.
This allows for the dev to clearly state which packaging they plan to ship. There is not
a known use case where an app will need to be built for both MSIX and MSI (as opposed to
iOS and Mac, where it is very common for an app to be created for both).
With this pattern, when resolving a path, the dev doesn't have to verbosely differentiate
between which path they want for their Windows package.
Surface is much wider than "common cases". The proposal says: "simplified path for
common cases via the cross-platform API, and fine-grained control when platform-specific
behavior matters."
Since the actual path resolution is not made more complicated by how many paths we
expose, there is no benefit to limiting which paths are allowed.
Instead, by simply reflecting exactly what each platforms API provides, we give the
client full control with no opinion forced on them.
As long as the single low-level invocation to resolve a path works, all other paths will
work without issue.