Interface ImportEntity<K>

include a unique key that you can use to trace back the imported entity, because the path of the import in the bundled output will differ, whereas this key will remain the same.

specify the path to the resource to import. this path is equivalent to what you would typically pass on to build.resolve(...).

specify a namespace for the resource to inherit when it goes into the path resolution stage. by default, it inherits the namespace of the importer of this resource entity.

the value provided here is equivalent to what you would typically pass on to EsbuildResolveOptions.namespace | esbuild.ResolveOptions.namespace.

*mostly for internal use!**. dictates the importer of the resource entity that is to be imported. by default, it inherits the resolved path of the actual importer of your resource entity.

the value provided here is equivalent to what you would typically pass on to EsbuildResolveOptions.namespace | esbuild.ResolveOptions.importer.

while this is for internal use, you are free to override the importer to something else, for whatever reason. but be ready for the consequences! (CoNsEQueNCeS!!!)

specify the resolveDir for the resource to use when it goes into the path resolution stage. by default, it inherits the resolveDir of the resolved and loaded importer entity; however, if the importer's resolveDir was unset (or an empty string ""), then we'll fallback to using the importer's own path directory. and if the importer itself was set to an empty string (""), then we'll either use the cwd (current working directory) or absWorkingDir from the initial build options (aka "./").

the value provided here is equivalent to what you would typically pass on to EsbuildResolveOptions.resolveDir | esbuild.ResolveOptions.resolveDir.

specify the kind of import that is being performed by the importer entity. it doesn't really affect how the link will get embedded into the long-build's emitted js file (since it'll always be a dynamic import), however, could potentially affect the path resolution of your resource when it goes through the resolution stage. by default, it the kind gets set to "dynamic-import".

note that during the emission stage, the ImportedEntity.kind lists the on-transform based user-imports with the "user-import:" prefix. i.e. if you set the kind to "import-statement" here, then the resulting ImportedEntity.kind will read "user-import:import-statement".

the value provided here is equivalent to what you would typically pass on to EsbuildResolveOptions.kind | esbuild.ResolveOptions.kind.

associate a with import attribute to the import.

the value provided here is equivalent to what you would typically pass on to EsbuildResolveOptions.with | esbuild.ResolveOptions.with.

TODO: this feature is still defunct. and I'm unsure whether I want to include the with import attribute to the dynamic import of the prepared long-build step file.

attach any custom plugin data that should be included in the resolution stage of this imported resource. unlinke the namespace option, this field is not implicitly inherited from the importer when it is not specified.

specify if this import should be marked as an external resource, so that it neither gets resolved, nor loaded/bundled as an output file.

if you wish for your import's path to get resolved, but not loaded/bundled as a file, then you should either:

1. set external: false and then capture path during the onResolve stage, followed by setting external to true in the returned OnResolveResult.
2. set external: true and make sure that your path is pre-resolved within the transformation stage, by simply using build.resolve(...) to resolve its path in your plugin.