Skip to content

Commit

Permalink
feat: internal accessibility (#390)
Browse files Browse the repository at this point in the history
Respect the `@internal` jsdoc tag on types and members. Any type of member marked internal will not be exposed in the API of the module and in .d.ts. files (through `--strip-internal`).

Members (properties/methods) that are marked as `@internal` must also have an underscore prefix (i.e. `_myMethod`) and vice versa in order to ensure that implementers or subclasses won't modify  accessibility.

If a class implements (or an interface extends) an internal or private interface, that interface is erased from the implementer's API. So it is possible to use internal interfaces as bases, while still maintaining API integrity (related to #287).

Fixes #388

BREAKING CHANGE: member names that begin with underscore now must be marked as "@internal" in their jsdocs, which will cause them to disappear from type declaration files and jsii APIs.
  • Loading branch information
Elad Ben-Israel authored Mar 19, 2019
1 parent 7cc65a1 commit e232cb5
Show file tree
Hide file tree
Showing 44 changed files with 1,409 additions and 26 deletions.
89 changes: 89 additions & 0 deletions packages/jsii-calc/lib/compliance.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1335,3 +1335,92 @@ export class Constructors {
return new PrivateClass();
}
}

// internal can be used to represent members that can only be accessed from the current module
export class StripInternal {
public youSeeMe = 'hello';

/**
* This is an internal thing
* @internal
*/
public _youDontSeeMeAlthoughIamPublic = 'world'
}

/**
* @internal
*/
export class InternalClass {
public iAmNotHere = 'yes';
}

/**
* @internal
*/
export interface IInternalInterface {
prop: string;
}

/**
* @internal
*/
export enum InternalEnum {
Member1 = 12,
Member2 = 23
}

export interface IInterfaceWithInternal {
visible(): void;

/** @internal */
_hidden(): void;
}

export class ImplementsInterfaceWithInternal implements IInterfaceWithInternal {
visible() { }

/** @internal */
_hidden() { }

/** @internal */
_alsoHidden() { }

/** @internal */
_propertiesToo?: string;
}

export class ImplementsInterfaceWithInternalSubclass extends ImplementsInterfaceWithInternal {
/** @internal */
_alsoHidden() { }

/**
* @internal
*/
public _propertiesToo?: string;
}

//
// hidden interface erasure
// if a class/interface uses a hidden (private/internal) interface as base, the base will
// be erased from the API
//

interface IPrivateInterface {
private: string;
}

export interface ExtendsInternalInterface extends IInternalInterface {
boom: boolean
}

export class ImplementInternalInterface implements IInternalInterface {
prop = 'implement me'
}

export class ImplementsPrivateInterface implements IPrivateInterface {
public private = 'i came from private into the light'
}

export interface ExtendsPrivateInterface extends IPrivateInterface {
moreThings: string[];
}
136 changes: 135 additions & 1 deletion packages/jsii-calc/test/assembly.jsii
Original file line number Diff line number Diff line change
Expand Up @@ -1478,6 +1478,43 @@
}
]
},
"jsii-calc.ExtendsInternalInterface": {
"assembly": "jsii-calc",
"datatype": true,
"fqn": "jsii-calc.ExtendsInternalInterface",
"kind": "interface",
"name": "ExtendsInternalInterface",
"properties": [
{
"abstract": true,
"name": "boom",
"type": {
"primitive": "boolean"
}
}
]
},
"jsii-calc.ExtendsPrivateInterface": {
"assembly": "jsii-calc",
"datatype": true,
"fqn": "jsii-calc.ExtendsPrivateInterface",
"kind": "interface",
"name": "ExtendsPrivateInterface",
"properties": [
{
"abstract": true,
"name": "moreThings",
"type": {
"collection": {
"elementtype": {
"primitive": "string"
},
"kind": "array"
}
}
}
]
},
"jsii-calc.GiveMeStructs": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.GiveMeStructs",
Expand Down Expand Up @@ -1649,6 +1686,18 @@
}
]
},
"jsii-calc.IInterfaceWithInternal": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.IInterfaceWithInternal",
"kind": "interface",
"methods": [
{
"abstract": true,
"name": "visible"
}
],
"name": "IInterfaceWithInternal"
},
"jsii-calc.IInterfaceWithMethods": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.IInterfaceWithMethods",
Expand Down Expand Up @@ -1776,6 +1825,74 @@
}
]
},
"jsii-calc.ImplementInternalInterface": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.ImplementInternalInterface",
"initializer": {
"initializer": true
},
"kind": "class",
"name": "ImplementInternalInterface",
"properties": [
{
"name": "prop",
"type": {
"primitive": "string"
}
}
]
},
"jsii-calc.ImplementsInterfaceWithInternal": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.ImplementsInterfaceWithInternal",
"initializer": {
"initializer": true
},
"interfaces": [
{
"fqn": "jsii-calc.IInterfaceWithInternal"
}
],
"kind": "class",
"methods": [
{
"name": "visible",
"overrides": {
"fqn": "jsii-calc.IInterfaceWithInternal"
}
}
],
"name": "ImplementsInterfaceWithInternal"
},
"jsii-calc.ImplementsInterfaceWithInternalSubclass": {
"assembly": "jsii-calc",
"base": {
"fqn": "jsii-calc.ImplementsInterfaceWithInternal"
},
"fqn": "jsii-calc.ImplementsInterfaceWithInternalSubclass",
"initializer": {
"initializer": true
},
"kind": "class",
"name": "ImplementsInterfaceWithInternalSubclass"
},
"jsii-calc.ImplementsPrivateInterface": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.ImplementsPrivateInterface",
"initializer": {
"initializer": true
},
"kind": "class",
"name": "ImplementsPrivateInterface",
"properties": [
{
"name": "private",
"type": {
"primitive": "string"
}
}
]
},
"jsii-calc.ImplictBaseOfBase": {
"assembly": "jsii-calc",
"datatype": true,
Expand Down Expand Up @@ -3318,6 +3435,23 @@
],
"name": "StringEnum"
},
"jsii-calc.StripInternal": {
"assembly": "jsii-calc",
"fqn": "jsii-calc.StripInternal",
"initializer": {
"initializer": true
},
"kind": "class",
"name": "StripInternal",
"properties": [
{
"name": "youSeeMe",
"type": {
"primitive": "string"
}
}
]
},
"jsii-calc.Sum": {
"assembly": "jsii-calc",
"base": {
Expand Down Expand Up @@ -3949,5 +4083,5 @@
}
},
"version": "0.7.15",
"fingerprint": "IWSOEhdZzuvrss5K2WBjZCawXayV13yCAKTj/kJ9+mo="
"fingerprint": "iMxRj3lsHKNzSiBrjCyBH6Pp7Uvo+1Sxh/jN3hW+3nA="
}
Loading

0 comments on commit e232cb5

Please sign in to comment.