API Types

[QxxxGit]

This sort of thing is over my head but it’s something I’m willing to learn and put work into. I just don’t know where/how to begin. At the moment, I typically write out my own IPluginApi with the components, libs, and whatever else I need. After writing multiple plugins, it becomes a bit of a chore.

Ideally, it would be great to define components (and eventually all those GQL functions) with their proper types, and then for plugin developers to add a simple types dependency into their project e.g. yarn add --dev @types/stash

I was looking at pluginApi.d.ts and saw the loadableComponents namespace with some interfaces provided to the SceneCard and ScenePreview components. Out of curiosity, because I’m totally uneducated on this, is it possible to export the ISceneCardProperties from its original file then import it into pluginApi.d.ts so things wont have to be updated in two places?

Any thoughts would be greatly appreciated.

[DogmaDragon]

I’m even less knowledgeable than you but I believe @Valkyr has some of that work done here https://github.com/Valkyr-JS/StashPluginTemplate/tree/main/types.

[feederbox826]

In theory, you would be able to directly import the typings from the ui folder but it might be picky on transclusions, but it might be easier and possible to just generate type definitions from the TSX

Try importing the generated .d.ts files as they are only definition files and include no code

[Valkyr]

Sorry, didn’t see the notification about this until just now!

I’m still working types out as I go. I started with copying the pluginApi.d.ts same as you. And like you, found that there are bits spread out everywhere like with the scene card properties types.

I’ve not seen a way to pull that out other than literally copy/pasting, however that can be a rabbit hole of pulling parts from separate files. It also isn’t future proof if the API changes.

I’ve started using Zod for my latest plugin. Rather than just defining types, you write a schema describing the response, and it checks it at runtime to ensure the response fits the model you expect. This makes it easier to identify changes in API schema and handle any errors. It’s probably overkill as the API doesn’t seem to change that often other than additions, and if you’re still getting your head around types then this might be a little much.

For straight up types, it could be an idea to have a dedicated repo for us to manage plugin API types. We can add things as we go which should save each other time. I’d be happy to host and give you write access, or equally vice versa.

[xtc]

So spent some time today to put together a POC. The goal was to see if I could scan all tsx files and use that to build up the api. Its possible but man its a lot of ast processing. Given this file

I was able to find all uses of PatchComponent and extract their name as well as correct typing for props. This is just for the PluginApi.components section that will allow proper typing for say the patch namespace method (before,instead,after). With the code I have it would be easy to build out the reset of the typing from the pluginApi.tsx. Still a lot to do but lmk your thoughts. I’m using ts-morph and ts-query to help out with this. Wouldn’t be too hard to make this an automatic generator on say branch pushes and push to say github repo (free).

PatchComponent(
  "GalleryCard.Popovers",
  (props: IGalleryCardProps) => {
    function maybeRenderScenePopoverButton() {
    ...snip...

    return <>{maybeRenderPopoverButtonGroup()}</>;
  }
)
{
  name: 'GalleryCard.Popovers',
  propsType: {
    kind: 'object',
    name: 'IGalleryCardProps',
    props: {
      gallery: { kind: 'importRef', name: 'GQL.SlimGalleryDataFragment' },
      cardWidth: { kind: 'primitive', name: 'number | undefined' },
      selecting: { kind: 'primitive', name: 'boolean | undefined' },
      selected: { kind: 'primitive', name: 'boolean | undefined' },
      zoomIndex: { kind: 'primitive', name: 'number | undefined' },
      onSelectedChanged: {
        kind: 'function',
        name: '(selected: boolean, shiftKey: boolean) => void',
        args: { selected: [Object], shiftKey: [Object] },
        returns: { kind: 'primitive', name: 'void' }
      }
    }
  }
}
PatchComponent(
  "GalleryCard.Details",
  (props: IGalleryCardProps) => {
    return (
      <div className="gallery-card__details">
        ...snip..
      </div>
    );
  }
)
{
  name: 'GalleryCard.Details',
  propsType: {
    kind: 'object',
    name: 'IGalleryCardProps',
    props: {
      gallery: { kind: 'importRef', name: 'GQL.SlimGalleryDataFragment' },
      cardWidth: { kind: 'primitive', name: 'number | undefined' },
      selecting: { kind: 'primitive', name: 'boolean | undefined' },
      selected: { kind: 'primitive', name: 'boolean | undefined' },
      zoomIndex: { kind: 'primitive', name: 'number | undefined' },
      onSelectedChanged: {
        kind: 'function',
        name: '(selected: boolean, shiftKey: boolean) => void',
        args: { selected: [Object], shiftKey: [Object] },
        returns: { kind: 'primitive', name: 'void' }
      }
    }
  }
}
PatchComponent(
  "GalleryCard.Overlays",
  (props: IGalleryCardProps) => {
    return <StudioOverlay studio={props.gallery.studio} />;
  }
)
{
  name: 'GalleryCard.Overlays',
  propsType: {
    kind: 'object',
    name: 'IGalleryCardProps',
    props: {
      gallery: { kind: 'importRef', name: 'GQL.SlimGalleryDataFragment' },
      cardWidth: { kind: 'primitive', name: 'number | undefined' },
      selecting: { kind: 'primitive', name: 'boolean | undefined' },
      selected: { kind: 'primitive', name: 'boolean | undefined' },
      zoomIndex: { kind: 'primitive', name: 'number | undefined' },
      onSelectedChanged: {
        kind: 'function',
        name: '(selected: boolean, shiftKey: boolean) => void',
        args: { selected: [Object], shiftKey: [Object] },
        returns: { kind: 'primitive', name: 'void' }
      }
    }
  }
}
PatchComponent(
  "GalleryCard.Image",
  (props: IGalleryCardProps) => {
    const history = useHistory();

    return (
      <>
        <GalleryPreview
          ...snip..
      </>
    );
  }
)
{
  name: 'GalleryCard.Image',
  propsType: {
    kind: 'object',
    name: 'IGalleryCardProps',
    props: {
      gallery: { kind: 'importRef', name: 'GQL.SlimGalleryDataFragment' },
      cardWidth: { kind: 'primitive', name: 'number | undefined' },
      selecting: { kind: 'primitive', name: 'boolean | undefined' },
      selected: { kind: 'primitive', name: 'boolean | undefined' },
      zoomIndex: { kind: 'primitive', name: 'number | undefined' },
      onSelectedChanged: {
        kind: 'function',
        name: '(selected: boolean, shiftKey: boolean) => void',
        args: { selected: [Object], shiftKey: [Object] },
        returns: { kind: 'primitive', name: 'void' }
      }
    }
  }
}
PatchComponent(
  "GalleryCard",
  (props: IGalleryCardProps) => {
    return (
      <GridCard
       ...snip..
      />
    );
  }
)
{
  name: 'GalleryCard',
  propsType: {
    kind: 'object',
    name: 'IGalleryCardProps',
    props: {
      gallery: { kind: 'importRef', name: 'GQL.SlimGalleryDataFragment' },
      cardWidth: { kind: 'primitive', name: 'number | undefined' },
      selecting: { kind: 'primitive', name: 'boolean | undefined' },
      selected: { kind: 'primitive', name: 'boolean | undefined' },
      zoomIndex: { kind: 'primitive', name: 'number | undefined' },
      onSelectedChanged: {
        kind: 'function',
        name: '(selected: boolean, shiftKey: boolean) => void',
        args: { selected: [Object], shiftKey: [Object] },
        returns: { kind: 'primitive', name: 'void' }
      }
    }
  }
}

[xtc]

Ok make a lot of progress on this.

The code is found here : GitHub - xtc1337/stash-pluginapi-types-generator

I still need to finish a few things:

• some bugs with import resolving
• adding proper typing for before/after/instead
• add in support for PatchFunction

Don’t mind the amount of code.. after a while I realize the way I was going at this a bit overkill as I didn’t need all the information I’m currently parsing out from the AST.