feat(functions): export functionOptions #1904

billiegoose · 2021-10-18T16:01:11Z

Refactoring to make it easier to import the functionOptions schemas from @stoplight/spectral-functions. The function options are currently exposed on each individual function, but since the functions aren't very portable (relying on certain shims and specific bundler features that are not widely supported) that has caused issues for Stoplight developers working on the Spectral UX. By building and exporting a simple JSON object with all the functionOptions we can stay in sync with Spectral rather than maintain separate hard-coded values.

Does this PR introduce a breaking change?

Yes
No

Screenshots

Here's a (silly) example demonstrating the functionOptions being used in Storybook.

Spectral.Core.Function.Option.Schemas.mov

P0lip · 2021-10-18T16:05:20Z

@wmhilton make sure to commit all the files, it seems like you forgot to commit a few and tests fail.

specific bundler features that are not widely supported

ha? package exports is supported by all major bundlers

billiegoose · 2021-10-18T16:12:49Z

make sure to commit all the files, it seems like you forgot to commit a few and tests fail.

oh thank god. I was like "why the HELL are these linting errors saying it's of type any" I'm still on my first ☕

ha? package exports is supported by all major bundlers

We aren't all on the bleeding edge. Some of us still use Node 12 and Webpack 4!

billiegoose · 2021-10-18T16:14:17Z

OK it should be good now :D

P0lip

Overall OK.
I'd remove CustomFunctionOptionsSchema as it doesn't seem to bring much of a value.
Do keep in mind that this may break anytime, as Spectral will inevitably become fully ESM, so nested exports may break as they are never considered as a part of the public API.

packages/functions/src/schema/optionSchemas.ts

P0lip · 2021-10-18T16:24:27Z

packages/core/src/ruleset/rulesetFunction.ts

@@ -73,6 +73,8 @@ type SchemaDefinition = Schema | boolean;

 const DEFAULT_OPTIONS_VALIDATOR = (o: unknown): boolean => o === null;

+export type CustomFunctionOptionsSchema = Schema | null;


do we really need this type? Feels somewhat redundant 🤷‍♂️

I needed Schema to be exported.

not sure how you expect users to write custom functions when the type isn't exported...

P0lip · 2021-10-18T16:25:55Z

packages/functions/src/types.ts

@@ -0,0 +1,18 @@
+export enum CasingType {


can we move this back to casing function?

problem is it's as a value later, and casing.ts pulls in things from @stoplight/spectral-core, so I can't easily import it in optionSchemas.ts without it blowing up from a small JS file into a monster with dependencies.

The general pattern we've adopted at Stoplight is to put as many pure types into a separate types.ts file so that the types can be re-used without dragging around implementations. I'm not sure why Spectral doesn't do this.

The general pattern we've adopted at Stoplight is to put as many pure types into a separate types.ts

Never heard of it, to be honest. 😆
We do that in platform-internal, but it's quite project-dependant overall.

but yeah, I see now. It's alright.
TBH, I'll probably incorporate json-schema-to-typescript at some point, so we don't need to maintain these option types anymore.

json-schema-to-typescript

👀 ooooh

json-schema-to-typescript - we actually use it already in Spectral for ruleset-migrator. It works pretty well!

P0lip · 2021-10-18T16:33:49Z

We aren't all on the bleeding edge. Some of us still use Node 12 and Webpack 4!

FWIW Node.js 12 does support it just fine.
Well, Webpack v4 is becoming barely usable in the year of ESM, so we just gotta try to migrate, as it causes a true pain in the case of some of our packages (not Spectral tho). 😬

billiegoose · 2021-10-18T16:41:45Z

Do keep in mind that this may break anytime, as Spectral will inevitably become fully ESM, so nested exports may break as they are never considered as a part of the public API.

That's fine. It's still better than maintaining it separately in platform-internal IMO.

billiegoose · 2021-10-18T16:46:27Z

I'd remove CustomFunctionOptionsSchema as it doesn't seem to bring much of a value.

Currently Schema | null isn't exported. So it only works by type inference of the function arguments.

Would you like me to change

export const optionSchemas: Record<string, CustomFunctionOptionsSchema>

to

export const optionSchemas: Record<string, Parameters<typeof createRulesetFunction>[0]>

P0lip · 2021-10-18T18:08:22Z

export const optionSchemas: Record<string, Parameters[0]>

yeah, that's OK.

billiegoose · 2021-10-18T18:28:53Z

lol it ended up being

export const optionSchemas: Record<string, Parameters<typeof createRulesetFunction>[0]['input']>;

but it works

P0lip · 2021-10-18T18:38:53Z

packages/functions/src/optionSchemas.ts

+
+type CustomFunctionOptionsSchema = Parameters<typeof createRulesetFunction>[0]['input'];
+
+export const optionSchemas: Record<string, CustomFunctionOptionsSchema> = {


packages/functions/src/schema/index.ts you need this one too

oooh I didn't even notice that one ha.

# [@stoplight/spectral-functions-v1.3.0](https://github.com/stoplightio/spectral/compare/@stoplight/spectral-functions-v1.2.1...@stoplight/spectral-functions-v1.3.0) (2021-10-19) ### Features * **functions:** export functionOptions ([#1904](#1904)) ([2f26ed6](2f26ed6))

stoplight-bot · 2021-10-19T12:11:39Z

🎉 This PR is included in version @stoplight/spectral-functions-v1.3.0 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

pamgoodrich · 2021-10-22T15:35:58Z

@wmhilton : Is this something that customers would be interested in or is it something that impacts Stoplight devs only?

feat(functions): wip

4563605

billiegoose requested a review from P0lip October 18, 2021 16:01

feat(fu): fml

22f3534

P0lip reviewed Oct 18, 2021

View reviewed changes

chore(optionSchemas): move up

316331c

chore(core): cleanup

d5e4a42

P0lip reviewed Oct 18, 2021

View reviewed changes

P0lip added 2 commits October 18, 2021 21:42

build: node 16.8

28257d7

chore(functions): move schema opts

815c571

P0lip previously approved these changes Oct 18, 2021

View reviewed changes

build: YAML never disappoints

66748e1

P0lip dismissed their stale review via 66748e1 October 18, 2021 18:46

Merge branch 'develop' into feat/functions-schemas.json

56726b3

P0lip approved these changes Oct 18, 2021

View reviewed changes

P0lip assigned billiegoose Oct 18, 2021

P0lip added the enhancement New feature or request label Oct 18, 2021

P0lip merged commit 2f26ed6 into develop Oct 18, 2021

P0lip deleted the feat/functions-schemas.json branch October 18, 2021 18:53

stoplight-bot added the released label Oct 19, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(functions): export functionOptions #1904

feat(functions): export functionOptions #1904

billiegoose commented Oct 18, 2021

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021

billiegoose commented Oct 18, 2021

P0lip left a comment

P0lip Oct 18, 2021

billiegoose Oct 18, 2021

billiegoose Oct 18, 2021

P0lip Oct 18, 2021

billiegoose Oct 18, 2021

billiegoose Oct 18, 2021

P0lip Oct 18, 2021

P0lip Oct 18, 2021

billiegoose Oct 18, 2021

P0lip Oct 18, 2021

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021

billiegoose commented Oct 18, 2021

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021 •

edited

P0lip Oct 18, 2021

billiegoose Oct 18, 2021

stoplight-bot commented Oct 19, 2021

pamgoodrich commented Oct 22, 2021

		@@ -73,6 +73,8 @@ type SchemaDefinition = Schema \| boolean;

		const DEFAULT_OPTIONS_VALIDATOR = (o: unknown): boolean => o === null;

		export type CustomFunctionOptionsSchema = Schema \| null;


		type CustomFunctionOptionsSchema = Parameters<typeof createRulesetFunction>[0]['input'];

		export const optionSchemas: Record<string, CustomFunctionOptionsSchema> = {

feat(functions): export functionOptions #1904

feat(functions): export functionOptions #1904

Conversation

billiegoose commented Oct 18, 2021

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021

billiegoose commented Oct 18, 2021

P0lip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021

billiegoose commented Oct 18, 2021

P0lip commented Oct 18, 2021

billiegoose commented Oct 18, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stoplight-bot commented Oct 19, 2021

pamgoodrich commented Oct 22, 2021

billiegoose commented Oct 18, 2021 •

edited