@mrgrain/jsii-struct-builder v0.7.43
Build jsii structs with ease.
Jsii doesn't support TypeScript Utility Types like Partial
or Omit
, making it difficult to re-use existing struct interfaces.
With this package, you can work around that limitation and create brand new struct interfaces based on the jsii specification of any existing structs, their parents, and your custom specification.
From jsii's perspective, these structs are completely new types. From a maintainer's perspective, they require the same minimal effort as utility types do. Everybody wins!
Usage
Install with:
npm install --save-dev @mrgrain/jsii-struct-builder
Then add a new ProjenStruct
in your .projenrc.ts
file, passing a TypeScript project as the first parameter.
See the sections below for more usage details.
If you're not using projen
, see Use without projen
.
Requirements
Node.js >= 18
projen >= 0.65.0
Create from an existing Struct
Use the jsii FQN to mix in an existing struct.
Use omit()
to remove any properties you are not interested in.
new ProjenStruct(project, { name: 'MyProjectOptions' })
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
.omit('sampleCode', 'projenrcTs', 'projenrcTsOptions');
Adding new Properties
New properties can be added with a @jsii/spec
definition.
Complex types can be used and will be imported using their FQN.
Any existing properties of the same name will be replaced.
new ProjenStruct(project, { name: 'MyProjectOptions' })
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
.add(
{
name: 'booleanSetting',
type: { primitive: jsii.PrimitiveType.Boolean },
},
{
name: 'complexSetting',
type: { fqn: 'my_project.SomeEnum' },
}
);
Updating existing Properties
Existing properties can be updated.
The provided partial @jsii/spec
definition will be deep merged with the existing spec.
A convenience rename()
method is provided.
An update()
of the name
field has the same effect and can be combined with other updates.
new ProjenStruct(project, { name: 'MyProjectOptions'})
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
// Update a property
.update('typescriptVersion', { optional: false })
// Nested values can be updated
.update('sampleCode', {
docs: {
summary: 'New summary',
default: 'false',
}
}
)
// Rename a property
.rename('homepage', 'website'})
// ...this also does a rename
.update('eslint', {
name: 'lint',
optional: false,
});
Updating multiple properties
A callback function can be passed to updateEvery()
to update multiple properties at a time.
Use updateAll()
to uniformly update all properties.
A convenience allOptional()
method is provided to make all properties optional.
new ProjenStruct(project, { name: 'MyProjectOptions'})
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
// Use a callback to make conditional updates
.updateEvery((property) => {
if (!property.optional) {
return {
docs: {
remarks: 'This property is required.',
},
};
}
return {};
})
// Apply an update to all properties
.updateAll({
immutable: true,
})
// Mark all properties as optional
.allOptional();
Replacing properties
Existing properties can be replaced with a new @jsii/spec
definition.
If a different name
is provided, the property is also renamed.
A callback function can be passed to map()
to map every property to a new @jsii/spec
definition.
new ProjenStruct(project, { name: 'MyProjectOptions' })
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
// Replace a property with an entirely new definition
.replace('autoApproveOptions', {
name: 'autoApproveOptions',
type: { fqn: 'my_project.AutoApproveOptions' },
docs: {
summary: 'Configure the auto-approval workflow.'
}
})
// Passing a new name, will also rename the property
.replace('autoMergeOptions', {
name: 'mergeFlowOptions',
type: { fqn: 'my_project.MergeFlowOptions' },
})
// Use a callback to map every property to a new definition
.map((property) => {
if (property.protected) {
return {
...property,
protected: false,
docs: {
custom: {
'internal': 'true',
}
}
}
}
return property;
});
Filter properties
Arbitrary predicate functions can be used to filter properties. Only properties that meet the condition are kept.
Use omit()
and only()
for easy name based filtering.
A convenience withoutDeprecated()
method is also provided.
new ProjenStruct(project, { name: 'MyProjectOptions' })
.mixin(Struct.fromFqn('projen.typescript.TypeScriptProjectOptions'))
// Keep properties using arbitrary filters
.filter((prop) => !prop.optional)
// Keep or omit properties by name
.only('projenrcTs', 'projenrcTsOptions')
.omit('sampleCode')
// Remove all deprecated properties
.withoutDeprecated();
AWS CDK properties
A common use-case of this project is to expose arbitrary overrides in CDK constructs. For example, you may want to provide common AWS Lambda configuration, but allow a consuming user to override any arbitrary property.
To accomplish this, first create the new struct in your .projenrc.ts
file.
import { ProjenStruct, Struct } from '@mrgrain/jsii-struct-builder';
import { awscdk } from 'projen';
const project = new awscdk.AwsCdkConstructLibrary({
// your config - see https://projen.io/awscdk-construct.html
});
new ProjenStruct(project, { name: 'MyFunctionProps' })
.mixin(Struct.fromFqn('aws-cdk-lib.aws_lambda.FunctionProps'))
.withoutDeprecated()
.allOptional()
.omit('code'); // our construct always provides the code
Then use the new struct in your CDK construct.
// lib/MyFunction.ts
import { Code, Function, Runtime } from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';
import { join } from 'path';
import { MyFunctionProps } from './MyFunctionProps';
export class MyFunction extends Construct {
constructor(scope: Construct, id: string, props: MyFunctionProps = {}) {
super(scope, id);
new Function(this, 'Function', {
// sensible defaults
runtime: Runtime.NODEJS_18_X,
handler: 'index.handler',
// user provided props
...props,
// always force `code` from our construct
code: Code.fromAsset(join(__dirname, 'lambda-handler')),
});
}
}
Use without projen
It is not required to use projen with this package. You can use a renderer directly to create files:
const myProps = Struct.empty('@my-scope/my-pkg.MyFunctionProps')
.mixin(Struct.fromFqn('aws-cdk-lib.aws_lambda.FunctionProps'))
.withoutDeprecated();
const renderer = new TypeScriptRenderer();
fs.writeFileSync('my-props.ts', renderer.renderStruct(myProps));
Advanced usage
Struct
and ProjenStruct
both share the same interface.
This allows some advanced applications.
For example you can manipulate the source for re-use:
const base = Struct.fromFqn('projen.typescript.TypeScriptProjectOptions');
base.omit('sampleCode', 'projenrcTs', 'projenrcTsOptions');
Or you can mix in a ProjenStruct
with another:
const foo = new ProjenStruct(project, { name: 'Foo' });
const bar = new ProjenStruct(project, { name: 'Bar' });
bar.mixin(foo);
You can also use Struct
and ProjenStruct
as type of a property:
const foo = new ProjenStruct(project, { name: 'Foo' });
const bar = new ProjenStruct(project, { name: 'Bar' });
foo.add({
name: 'barSettings',
type: bar,
});
The default configuration makes assumptions about the new interface that are usually okay.
For more complex scenarios fqn
, filePath
and importLocations
can be used to influence the rendered output.
new JsiiInterface(project, {
name: 'MyProjectOptions',
fqn: 'my_project.nested.location.MyProjectOptions',
filePath: 'src/nested/my-project-options.ts',
importLocations: {
my_project: '../enums',
},
}).add({
name: 'complexSetting',
type: { fqn: 'my_project.SomeEnum' },
});
4 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
5 months ago
5 months ago
5 months ago
5 months ago
7 months ago
4 months ago
4 months ago
4 months ago
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago