@suss/contract-serverless 0.3.2-0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +205 -0
- package/README.md +77 -0
- package/dist/index.cjs +623 -0
- package/dist/index.d.cts +124 -0
- package/dist/index.d.ts +124 -0
- package/dist/index.js +582 -0
- package/package.json +64 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { CloudFormationTemplate } from '@suss/manifest-aws';
|
|
2
|
+
import { BehavioralSummary } from '@suss/behavioral-ir';
|
|
3
|
+
|
|
4
|
+
/** One entry in a function's `events` list, as written. */
|
|
5
|
+
type ServerlessEvent = Record<string, unknown>;
|
|
6
|
+
/** One entry of the `functions` block, as written. */
|
|
7
|
+
interface ServerlessFunctionDefinition {
|
|
8
|
+
handler?: unknown;
|
|
9
|
+
environment?: unknown;
|
|
10
|
+
runtime?: unknown;
|
|
11
|
+
events?: unknown;
|
|
12
|
+
name?: unknown;
|
|
13
|
+
}
|
|
14
|
+
interface ServerlessDocument {
|
|
15
|
+
service?: unknown;
|
|
16
|
+
provider?: Record<string, unknown>;
|
|
17
|
+
functions?: Record<string, ServerlessFunctionDefinition>;
|
|
18
|
+
custom?: Record<string, unknown>;
|
|
19
|
+
plugins?: unknown;
|
|
20
|
+
/** Raw CloudFormation, in the framework's `{ Resources, Outputs }` shape. */
|
|
21
|
+
resources?: Record<string, unknown>;
|
|
22
|
+
[key: string]: unknown;
|
|
23
|
+
}
|
|
24
|
+
/** In the framework's own order of preference. */
|
|
25
|
+
declare const SERVICE_FILE_NAMES: readonly ["serverless.yml", "serverless.yaml", "serverless.json"];
|
|
26
|
+
/** Recognized in order to be reported rather than read. */
|
|
27
|
+
declare const PROGRAM_SERVICE_FILE_NAMES: readonly ["serverless.ts", "serverless.js"];
|
|
28
|
+
type ServiceLocation = {
|
|
29
|
+
kind: "readable";
|
|
30
|
+
file: string;
|
|
31
|
+
} | {
|
|
32
|
+
kind: "program";
|
|
33
|
+
file: string;
|
|
34
|
+
} | {
|
|
35
|
+
kind: "missing";
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* A path that points at a file is taken as that file. A directory is
|
|
39
|
+
* searched parseable spellings first, so a service with both a yml and
|
|
40
|
+
* a ts is read from the yml.
|
|
41
|
+
*/
|
|
42
|
+
declare function locateServiceFile(candidate: string): ServiceLocation;
|
|
43
|
+
/** Null when the path contains no service file this reader can parse. */
|
|
44
|
+
declare function findServiceFile(candidate: string): string | null;
|
|
45
|
+
/** Throws when the file is missing or does not parse to an object. */
|
|
46
|
+
declare function loadServerlessDocument(servicePath: string): ServerlessDocument;
|
|
47
|
+
|
|
48
|
+
/** A wiring the document declares that this reader did not translate. */
|
|
49
|
+
interface UnreadWiring {
|
|
50
|
+
/** Null for a service-level abstention. */
|
|
51
|
+
functionName: string | null;
|
|
52
|
+
/** The event kind as the framework spells it, or the block name. */
|
|
53
|
+
kind: string;
|
|
54
|
+
reason: string;
|
|
55
|
+
}
|
|
56
|
+
interface TranslatedService {
|
|
57
|
+
/** The functions block as SAM resources, with provider defaults in Globals. */
|
|
58
|
+
functions: CloudFormationTemplate;
|
|
59
|
+
/** The `resources:` block verbatim, or null when the document has none. */
|
|
60
|
+
resources: CloudFormationTemplate | null;
|
|
61
|
+
unread: UnreadWiring[];
|
|
62
|
+
}
|
|
63
|
+
declare function translateService(document: ServerlessDocument): TranslatedService;
|
|
64
|
+
|
|
65
|
+
/** A symbolic token is the reference text as written, minus the wrapper. */
|
|
66
|
+
type ResolvedString = {
|
|
67
|
+
kind: "resolved";
|
|
68
|
+
value: string;
|
|
69
|
+
} | {
|
|
70
|
+
kind: "symbolic";
|
|
71
|
+
token: string;
|
|
72
|
+
};
|
|
73
|
+
/** A whole-value reference can also resolve to a non-string subtree. */
|
|
74
|
+
type ResolvedValue = {
|
|
75
|
+
kind: "resolved";
|
|
76
|
+
value: unknown;
|
|
77
|
+
} | {
|
|
78
|
+
kind: "symbolic";
|
|
79
|
+
token: string;
|
|
80
|
+
};
|
|
81
|
+
/** Resolves `${...}` references against one parsed serverless.yml document. */
|
|
82
|
+
interface VariableResolver {
|
|
83
|
+
/** A whole `${self:...}` reference resolves to whatever is at that
|
|
84
|
+
* path, object or scalar. */
|
|
85
|
+
resolveValue(raw: unknown): ResolvedValue;
|
|
86
|
+
/** A whole reference resolving to an object or array is symbolic, since no string was stated. */
|
|
87
|
+
resolveString(raw: string): ResolvedString;
|
|
88
|
+
/** A reference to anything the framework does not define is left
|
|
89
|
+
* exactly as written. */
|
|
90
|
+
resolveTemplateTree(value: unknown): unknown;
|
|
91
|
+
}
|
|
92
|
+
declare function createVariableResolver(document: Record<string, unknown>): VariableResolver;
|
|
93
|
+
|
|
94
|
+
/** A SAM `Events` entry, which is what the CloudFormation reader consumes. */
|
|
95
|
+
interface SamEvent {
|
|
96
|
+
Type: string;
|
|
97
|
+
Properties?: Record<string, unknown>;
|
|
98
|
+
}
|
|
99
|
+
/** What one event entry produced, or why it produced nothing. */
|
|
100
|
+
type EventTranslation = {
|
|
101
|
+
kind: "event";
|
|
102
|
+
event: SamEvent;
|
|
103
|
+
} | {
|
|
104
|
+
kind: "abstained";
|
|
105
|
+
reason: string;
|
|
106
|
+
};
|
|
107
|
+
interface EventContext {
|
|
108
|
+
resolver: VariableResolver;
|
|
109
|
+
}
|
|
110
|
+
/** Keyed by the name the framework's own schema uses for each event kind. */
|
|
111
|
+
declare const EVENT_TRANSLATIONS: Record<string, (raw: unknown, ctx: EventContext) => EventTranslation>;
|
|
112
|
+
|
|
113
|
+
interface ServerlessToSummariesOptions {
|
|
114
|
+
/** Override the logical source file recorded on each summary. */
|
|
115
|
+
source?: string;
|
|
116
|
+
/** Called once per wiring the reader did not translate. Defaults to
|
|
117
|
+
* printing a line on stderr. */
|
|
118
|
+
onUnread?: (wiring: UnreadWiring) => void;
|
|
119
|
+
}
|
|
120
|
+
declare function serverlessToSummaries(document: ServerlessDocument, options?: ServerlessToSummariesOptions): BehavioralSummary[];
|
|
121
|
+
/** The path may be the service file itself or the directory it is in. */
|
|
122
|
+
declare function serverlessFileToSummaries(servicePath: string, options?: ServerlessToSummariesOptions): BehavioralSummary[];
|
|
123
|
+
|
|
124
|
+
export { EVENT_TRANSLATIONS, PROGRAM_SERVICE_FILE_NAMES, type ResolvedString, type ResolvedValue, SERVICE_FILE_NAMES, type ServerlessDocument, type ServerlessEvent, type ServerlessFunctionDefinition, type ServerlessToSummariesOptions, type ServiceLocation, type TranslatedService, type UnreadWiring, type VariableResolver, createVariableResolver, findServiceFile, loadServerlessDocument, locateServiceFile, serverlessFileToSummaries, serverlessToSummaries, translateService };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { CloudFormationTemplate } from '@suss/manifest-aws';
|
|
2
|
+
import { BehavioralSummary } from '@suss/behavioral-ir';
|
|
3
|
+
|
|
4
|
+
/** One entry in a function's `events` list, as written. */
|
|
5
|
+
type ServerlessEvent = Record<string, unknown>;
|
|
6
|
+
/** One entry of the `functions` block, as written. */
|
|
7
|
+
interface ServerlessFunctionDefinition {
|
|
8
|
+
handler?: unknown;
|
|
9
|
+
environment?: unknown;
|
|
10
|
+
runtime?: unknown;
|
|
11
|
+
events?: unknown;
|
|
12
|
+
name?: unknown;
|
|
13
|
+
}
|
|
14
|
+
interface ServerlessDocument {
|
|
15
|
+
service?: unknown;
|
|
16
|
+
provider?: Record<string, unknown>;
|
|
17
|
+
functions?: Record<string, ServerlessFunctionDefinition>;
|
|
18
|
+
custom?: Record<string, unknown>;
|
|
19
|
+
plugins?: unknown;
|
|
20
|
+
/** Raw CloudFormation, in the framework's `{ Resources, Outputs }` shape. */
|
|
21
|
+
resources?: Record<string, unknown>;
|
|
22
|
+
[key: string]: unknown;
|
|
23
|
+
}
|
|
24
|
+
/** In the framework's own order of preference. */
|
|
25
|
+
declare const SERVICE_FILE_NAMES: readonly ["serverless.yml", "serverless.yaml", "serverless.json"];
|
|
26
|
+
/** Recognized in order to be reported rather than read. */
|
|
27
|
+
declare const PROGRAM_SERVICE_FILE_NAMES: readonly ["serverless.ts", "serverless.js"];
|
|
28
|
+
type ServiceLocation = {
|
|
29
|
+
kind: "readable";
|
|
30
|
+
file: string;
|
|
31
|
+
} | {
|
|
32
|
+
kind: "program";
|
|
33
|
+
file: string;
|
|
34
|
+
} | {
|
|
35
|
+
kind: "missing";
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* A path that points at a file is taken as that file. A directory is
|
|
39
|
+
* searched parseable spellings first, so a service with both a yml and
|
|
40
|
+
* a ts is read from the yml.
|
|
41
|
+
*/
|
|
42
|
+
declare function locateServiceFile(candidate: string): ServiceLocation;
|
|
43
|
+
/** Null when the path contains no service file this reader can parse. */
|
|
44
|
+
declare function findServiceFile(candidate: string): string | null;
|
|
45
|
+
/** Throws when the file is missing or does not parse to an object. */
|
|
46
|
+
declare function loadServerlessDocument(servicePath: string): ServerlessDocument;
|
|
47
|
+
|
|
48
|
+
/** A wiring the document declares that this reader did not translate. */
|
|
49
|
+
interface UnreadWiring {
|
|
50
|
+
/** Null for a service-level abstention. */
|
|
51
|
+
functionName: string | null;
|
|
52
|
+
/** The event kind as the framework spells it, or the block name. */
|
|
53
|
+
kind: string;
|
|
54
|
+
reason: string;
|
|
55
|
+
}
|
|
56
|
+
interface TranslatedService {
|
|
57
|
+
/** The functions block as SAM resources, with provider defaults in Globals. */
|
|
58
|
+
functions: CloudFormationTemplate;
|
|
59
|
+
/** The `resources:` block verbatim, or null when the document has none. */
|
|
60
|
+
resources: CloudFormationTemplate | null;
|
|
61
|
+
unread: UnreadWiring[];
|
|
62
|
+
}
|
|
63
|
+
declare function translateService(document: ServerlessDocument): TranslatedService;
|
|
64
|
+
|
|
65
|
+
/** A symbolic token is the reference text as written, minus the wrapper. */
|
|
66
|
+
type ResolvedString = {
|
|
67
|
+
kind: "resolved";
|
|
68
|
+
value: string;
|
|
69
|
+
} | {
|
|
70
|
+
kind: "symbolic";
|
|
71
|
+
token: string;
|
|
72
|
+
};
|
|
73
|
+
/** A whole-value reference can also resolve to a non-string subtree. */
|
|
74
|
+
type ResolvedValue = {
|
|
75
|
+
kind: "resolved";
|
|
76
|
+
value: unknown;
|
|
77
|
+
} | {
|
|
78
|
+
kind: "symbolic";
|
|
79
|
+
token: string;
|
|
80
|
+
};
|
|
81
|
+
/** Resolves `${...}` references against one parsed serverless.yml document. */
|
|
82
|
+
interface VariableResolver {
|
|
83
|
+
/** A whole `${self:...}` reference resolves to whatever is at that
|
|
84
|
+
* path, object or scalar. */
|
|
85
|
+
resolveValue(raw: unknown): ResolvedValue;
|
|
86
|
+
/** A whole reference resolving to an object or array is symbolic, since no string was stated. */
|
|
87
|
+
resolveString(raw: string): ResolvedString;
|
|
88
|
+
/** A reference to anything the framework does not define is left
|
|
89
|
+
* exactly as written. */
|
|
90
|
+
resolveTemplateTree(value: unknown): unknown;
|
|
91
|
+
}
|
|
92
|
+
declare function createVariableResolver(document: Record<string, unknown>): VariableResolver;
|
|
93
|
+
|
|
94
|
+
/** A SAM `Events` entry, which is what the CloudFormation reader consumes. */
|
|
95
|
+
interface SamEvent {
|
|
96
|
+
Type: string;
|
|
97
|
+
Properties?: Record<string, unknown>;
|
|
98
|
+
}
|
|
99
|
+
/** What one event entry produced, or why it produced nothing. */
|
|
100
|
+
type EventTranslation = {
|
|
101
|
+
kind: "event";
|
|
102
|
+
event: SamEvent;
|
|
103
|
+
} | {
|
|
104
|
+
kind: "abstained";
|
|
105
|
+
reason: string;
|
|
106
|
+
};
|
|
107
|
+
interface EventContext {
|
|
108
|
+
resolver: VariableResolver;
|
|
109
|
+
}
|
|
110
|
+
/** Keyed by the name the framework's own schema uses for each event kind. */
|
|
111
|
+
declare const EVENT_TRANSLATIONS: Record<string, (raw: unknown, ctx: EventContext) => EventTranslation>;
|
|
112
|
+
|
|
113
|
+
interface ServerlessToSummariesOptions {
|
|
114
|
+
/** Override the logical source file recorded on each summary. */
|
|
115
|
+
source?: string;
|
|
116
|
+
/** Called once per wiring the reader did not translate. Defaults to
|
|
117
|
+
* printing a line on stderr. */
|
|
118
|
+
onUnread?: (wiring: UnreadWiring) => void;
|
|
119
|
+
}
|
|
120
|
+
declare function serverlessToSummaries(document: ServerlessDocument, options?: ServerlessToSummariesOptions): BehavioralSummary[];
|
|
121
|
+
/** The path may be the service file itself or the directory it is in. */
|
|
122
|
+
declare function serverlessFileToSummaries(servicePath: string, options?: ServerlessToSummariesOptions): BehavioralSummary[];
|
|
123
|
+
|
|
124
|
+
export { EVENT_TRANSLATIONS, PROGRAM_SERVICE_FILE_NAMES, type ResolvedString, type ResolvedValue, SERVICE_FILE_NAMES, type ServerlessDocument, type ServerlessEvent, type ServerlessFunctionDefinition, type ServerlessToSummariesOptions, type ServiceLocation, type TranslatedService, type UnreadWiring, type VariableResolver, createVariableResolver, findServiceFile, loadServerlessDocument, locateServiceFile, serverlessFileToSummaries, serverlessToSummaries, translateService };
|