Skip to content

Commit b938cb9

Browse files
shazronshazron
authored
fix: generate typings from jsdoc (#35)
1 parent b65c916 commit b938cb9

File tree

3 files changed

+184
-4
lines changed

3 files changed

+184
-4
lines changed

‎jsconfig.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,8 @@
33
"include": [
44
"jest"
55
]
6-
}
7-
}
6+
},
7+
"include": [
8+
"lib/**/*.js"
9+
]
10+
}

‎package.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@
1212
"test": "npm run unit && npm run lint",
1313
"unit": "jest -c jest.config.js",
1414
"e2e": "jest -c jest.e2e.config.js",
15-
"generate-jsdoc": "jsdoc2md -f index.js 'lib/**/*.js' > doc/api.md"
15+
"jsdoc": "jsdoc2md -f index.js 'lib/**/*.js' > doc/api.md",
16+
"typings": "jsdoc -t node_modules/tsd-jsdoc/dist -r lib -d .",
17+
"generate-docs": "npm run jsdoc && npm run typings"
1618
},
1719
"author": "Adobe Inc.",
1820
"license": "Apache-2.0",
@@ -43,7 +45,8 @@
4345
"eslint-plugin-promise": "^4.2.1",
4446
"eslint-plugin-standard": "^4.0.1",
4547
"jest": "^24.9.0",
46-
"jsdoc-to-markdown": "^5.0.2"
48+
"jsdoc-to-markdown": "^5.0.2",
49+
"tsd-jsdoc": "^2.4.0"
4750
},
4851
"dependencies": {
4952
"@adobe/aio-lib-core-errors": "^3.0.0",

‎types.d.ts‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
/**
2+
* StateStore put options
3+
*
4+
* @typedef StateStorePutOptions
5+
* @type {object}
6+
* @property {number} ttl time-to-live for key-value pair in seconds, defaults to 24 hours (86400s). Set to < 0 for no expiry. A
7+
* value of 0 sets default.
8+
*/
9+
declare type StateStorePutOptions = {
10+
ttl: number;
11+
};
12+
13+
/**
14+
* StateStore get return object
15+
*
16+
* @typedef StateStoreGetReturnValue
17+
* @type {object}
18+
* @property {string|null} expiration ISO date string of expiration time for the key-value pair, if the ttl is infinite
19+
* expiration=null
20+
* @property {any} value the value set by put
21+
*/
22+
declare type StateStoreGetReturnValue = {
23+
expiration: string | null;
24+
value: any;
25+
};
26+
27+
/**
28+
* @abstract
29+
* @class StateStore
30+
* @classdesc Cloud State Management
31+
* @hideconstructor
32+
*/
33+
declare class StateStore {
34+
/**
35+
* Retrieves the state value for given key.
36+
* If the key doesn't exist returns undefined.
37+
*
38+
* @param {string} key state key identifier
39+
* @returns {Promise<StateStoreGetReturnValue>} get response holding value and additional info
40+
* @memberof StateStore
41+
*/
42+
get(key: string): Promise<StateStoreGetReturnValue>;
43+
/**
44+
* Creates or updates a state key-value pair
45+
*
46+
* @param {string} key state key identifier
47+
* @param {any} value state value
48+
* @param {StateStorePutOptions} [options={}] put options
49+
* @returns {Promise<string>} key
50+
* @memberof StateStore
51+
*/
52+
put(key: string, value: any, options?: StateStorePutOptions): Promise<string>;
53+
/**
54+
* Deletes a state key-value pair
55+
*
56+
* @param {string} key state key identifier
57+
* @returns {Promise<string>} key of deleted state or `null` if state does not exists
58+
* @memberof StateStore
59+
*/
60+
delete(key: string): Promise<string>;
61+
}
62+
63+
/**
64+
* State lib custom errors.
65+
* `e.sdkDetails` provides additional context for each error (e.g. function parameter)
66+
*
67+
* @typedef StateLibErrors
68+
* @type {object}
69+
* @property {StateLibError} ERROR_BAD_ARGUMENT this error is thrown when an argument is missing or has invalid type
70+
* @property {StateLibError} ERROR_NOT_IMPLEMENTED this error is thrown when a method is not implemented or when calling
71+
* methods directly on the abstract class (StateStore).
72+
* @property {StateLibError} ERROR_PAYLOAD_TOO_LARGE this error is thrown when the state key, state value or underlying request payload size
73+
* exceeds the specified limitations.
74+
* @property {StateLibError} ERROR_BAD_CREDENTIALS this error is thrown when the supplied init credentials are invalid.
75+
* @property {StateLibError} ERROR_INTERNAL this error is thrown when an unknown error is thrown by the underlying
76+
* DB provider or TVM server for credential exchange. More details can be found in `e.sdkDetails._internal`.
77+
*/
78+
declare type StateLibErrors = {
79+
ERROR_BAD_ARGUMENT: StateLibError;
80+
ERROR_NOT_IMPLEMENTED: StateLibError;
81+
ERROR_PAYLOAD_TOO_LARGE: StateLibError;
82+
ERROR_BAD_CREDENTIALS: StateLibError;
83+
ERROR_INTERNAL: StateLibError;
84+
};
85+
86+
/**
87+
* An object holding the OpenWhisk credentials
88+
*
89+
* @typedef OpenWhiskCredentials
90+
* @type {object}
91+
* @property {string} namespace user namespace
92+
* @property {string} auth auth key
93+
*/
94+
declare type OpenWhiskCredentials = {
95+
namespace: string;
96+
auth: string;
97+
};
98+
99+
/**
100+
* An object holding the Azure Cosmos resource credentials with permissions on a single partition and container
101+
*
102+
* @typedef AzureCosmosPartitionResourceCredentials
103+
* @type {object}
104+
* @property {string} endpoint cosmosdb resource endpoint
105+
* @property {string} resourceToken cosmosdb resource token restricted to the partitionKey
106+
* @property {string} databaseId id for cosmosdb database
107+
* @property {string} containerId id for cosmosdb container within database
108+
* @property {string} partitionKey key for cosmosdb partition within container authorized by resource token
109+
*
110+
*/
111+
declare type AzureCosmosPartitionResourceCredentials = {
112+
endpoint: string;
113+
resourceToken: string;
114+
databaseId: string;
115+
containerId: string;
116+
partitionKey: string;
117+
};
118+
119+
/**
120+
* An object holding the Azure Cosmos account master key
121+
*
122+
* @typedef AzureCosmosMasterCredentials
123+
* @type {object}
124+
* @property {string} endpoint cosmosdb resource endpoint
125+
* @property {string} masterKey cosmosdb account masterKey
126+
* @property {string} databaseId id for cosmosdb database
127+
* @property {string} containerId id for cosmosdb container within database
128+
* @property {string} partitionKey key for cosmosdb partition where data will be stored
129+
*
130+
*/
131+
declare type AzureCosmosMasterCredentials = {
132+
endpoint: string;
133+
masterKey: string;
134+
databaseId: string;
135+
containerId: string;
136+
partitionKey: string;
137+
};
138+
139+
/**
140+
* Initializes and returns the key-value-store SDK.
141+
*
142+
* To use the SDK you must either provide your
143+
* [OpenWhisk credentials]{@link OpenWhiskCredentials} in
144+
* `config.ow` or your own
145+
* [Azure Cosmos credentials]{@link AzureCosmosMasterCredentials} in `config.cosmos`.
146+
*
147+
* OpenWhisk credentials can also be read from environment variables `__OW_NAMESPACE` and `__OW_API_KEY`.
148+
*
149+
* @param {object} [config={}] used to init the sdk
150+
*
151+
* @param {OpenWhiskCredentials} [config.ow]
152+
* {@link OpenWhiskCredentials}. Set those if you want
153+
* to use ootb credentials to access the state management service. OpenWhisk
154+
* namespace and auth can also be passed through environment variables:
155+
* `__OW_NAMESPACE` and `__OW_API_KEY`
156+
*
157+
* @param {AzureCosmosMasterCredentials|AzureCosmosPartitionResourceCredentials} [config.cosmos]
158+
* [Azure Cosmos resource credentials]{@link AzureCosmosPartitionResourceCredentials} or
159+
* [Azure Cosmos account credentials]{@link AzureCosmosMasterCredentials}
160+
*
161+
* @param {object} [config.tvm] tvm configuration, applies only when passing OpenWhisk credentials
162+
* @param {string} [config.tvm.apiUrl] alternative tvm api url.
163+
* @param {string} [config.tvm.cacheFile] alternative tvm cache file, set to `false` to disable caching of temporary credentials.
164+
* @returns {Promise<StateStore>} A StateStore instance
165+
*/
166+
declare function init(config?: {
167+
ow?: OpenWhiskCredentials;
168+
cosmos?: AzureCosmosMasterCredentials | AzureCosmosPartitionResourceCredentials;
169+
tvm?: {
170+
apiUrl?: string;
171+
cacheFile?: string;
172+
};
173+
}): Promise<StateStore>;
174+

0 commit comments

Comments
 (0)