@bifravst/aws-ssm-settings-helpers 1.0.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Nordic Semiconductor ASA | nordicsemi.no
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,15 @@
+# AWS SSM Settings helpers [![npm version](https://img.shields.io/npm/v/@bifravst/aws-ssm-settings-helpers.svg)](https://www.npmjs.com/package/@bifravst/aws-ssm-settings-helpers)
+
+[![GitHub Actions](https://github.com/bifravst/aws-ssm-settings-helpers/workflows/Test%20and%20Release/badge.svg)](https://github.com/bifravst/aws-ssm-settings-helpers/actions)
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+[![Renovate](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com)
+[![@commitlint/config-conventional](https://img.shields.io/badge/%40commitlint-config--conventional-brightgreen)](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier/)
+[![ESLint: TypeScript](https://img.shields.io/badge/ESLint-TypeScript-blue.svg)](https://github.com/typescript-eslint/typescript-eslint)
+
+Helper functions written in TypeScript for storing and retrieving application
+settings in AWS SSM Parameter Store.
+
+## Installation
+
+    npm i --save --save-exact @bifravst/aws-ssm-settings-helpers

package/dist/isNotEmpty.d.ts

@@ -0,0 +1,2 @@
+export declare const isEmpty: (s: string) => boolean;
+export declare const isNotEmpty: (s: string) => boolean;

package/dist/isNotEmpty.js

@@ -0,0 +1,2 @@
+export const isEmpty = (s) => s.length === 0;
+export const isNotEmpty = (s) => !isEmpty(s);

package/dist/isNullOrUndefined.d.ts

@@ -0,0 +1 @@
+export declare const isNullOrUndefined: (arg?: unknown) => arg is null | undefined;

package/dist/isNullOrUndefined.js

@@ -0,0 +1 @@
+export const isNullOrUndefined = (arg) => arg === undefined || arg === null;

package/dist/paginate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Iteratively follows paginated results.
+ * NOTE: This method has no upper runtime limit and may time out.
+ */
+export declare const paginate: ({ paginator, startKey, }: {
+    paginator: (startKey?: any) => Promise<unknown>;
+    startKey?: any;
+}) => Promise<void>;

package/dist/paginate.js

@@ -0,0 +1,17 @@
+import { isEmpty } from './isNotEmpty.js';
+import { isNullOrUndefined } from './isNullOrUndefined.js';
+/**
+ * Iteratively follows paginated results.
+ * NOTE: This method has no upper runtime limit and may time out.
+ */
+export const paginate = async ({ paginator, startKey, }) => {
+    const nextStartKey = await paginator(startKey);
+    if (isNullOrUndefined(nextStartKey))
+        return;
+    if (typeof nextStartKey === 'string' && isEmpty(nextStartKey))
+        return;
+    await paginate({
+        paginator,
+        startKey: nextStartKey,
+    });
+};

package/dist/settings.d.ts

@@ -0,0 +1,35 @@
+import { SSMClient } from '@aws-sdk/client-ssm';
+export declare const settingsPath: ({ stackName, scope, property, }: {
+    stackName: string;
+    scope: string;
+    property?: string | undefined;
+}) => string;
+export declare const getSettings: <Settings extends Record<string, string>>({ ssm, stackName, scope, }: {
+    ssm: SSMClient;
+    stackName: string;
+    scope: string;
+}) => () => Promise<Settings>;
+export declare const putSettings: ({ ssm, stackName, scope, }: {
+    ssm: SSMClient;
+    stackName: string;
+    scope: string;
+}) => ({ property, value, deleteBeforeUpdate, }: {
+    property: string;
+    value: string;
+    /**
+     * Useful when depending on the parameter having version 1, e.g. for use in CloudFormation
+     */
+    deleteBeforeUpdate?: boolean | undefined;
+}) => Promise<{
+    name: string;
+}>;
+export declare const deleteSettings: ({ ssm, stackName, scope, }: {
+    ssm: SSMClient;
+    stackName: string;
+    scope: string;
+}) => ({ property }: {
+    property: string;
+}) => Promise<{
+    name: string;
+}>;
+export declare const getSettingsOptional: <Settings extends Record<string, string>, Default>(args: Parameters<typeof getSettings>[0]) => (defaultValue: Default) => Promise<Settings | Default>;

package/dist/settings.js

@@ -0,0 +1,86 @@
+import { DeleteParameterCommand, GetParametersByPathCommand, PutParameterCommand, SSMClient, } from '@aws-sdk/client-ssm';
+import { paginate } from './paginate.js';
+const scopeRx = new RegExp(`^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$`);
+const validScope = (scope) => scopeRx.test(scope);
+export const settingsPath = ({ stackName, scope, property, }) => {
+    if (!validScope(scope))
+        throw new Error(`Invalid scope name`);
+    const base = `/${stackName}/${scope}`;
+    return property === undefined ? base : `${base}/${property}`;
+};
+const settingsName = ({ stackName, scope, property, }) => settingsPath({ stackName, scope, property });
+export const getSettings = ({ ssm, stackName, scope, }) => async () => {
+    const Path = settingsPath({ stackName, scope });
+    const Parameters = [];
+    await paginate({
+        paginator: async (NextToken) => ssm
+            .send(new GetParametersByPathCommand({
+            Path,
+            Recursive: true,
+            NextToken,
+        }))
+            .then(({ Parameters: p, NextToken }) => {
+            if (p !== undefined)
+                Parameters.push(...p);
+            return NextToken;
+        }),
+    });
+    if (Parameters.length === 0)
+        throw new Error(`System not configured: ${Path}!`);
+    return Parameters.map(({ Name, ...rest }) => ({
+        ...rest,
+        Name: Name?.replace(`${Path}/`, ''),
+    })).reduce((settings, { Name, Value }) => ({
+        ...settings,
+        [Name ?? '']: Value ?? '',
+    }), {});
+};
+export const putSettings = ({ ssm, stackName, scope, }) => async ({ property, value, deleteBeforeUpdate, }) => {
+    const Name = settingsName({ stackName, scope, property });
+    if (deleteBeforeUpdate ?? false) {
+        try {
+            await ssm.send(new DeleteParameterCommand({
+                Name,
+            }));
+        }
+        catch {
+            // pass
+        }
+    }
+    await ssm.send(new PutParameterCommand({
+        Name,
+        Value: value,
+        Type: 'String',
+        Overwrite: !(deleteBeforeUpdate ?? false),
+    }));
+    return { name: Name };
+};
+export const deleteSettings = ({ ssm, stackName, scope, }) => async ({ property }) => {
+    const Name = settingsName({ stackName, scope, property });
+    try {
+        await ssm.send(new DeleteParameterCommand({
+            Name,
+        }));
+    }
+    catch (error) {
+        if (error.name === 'ParameterNotFound') {
+            // pass
+        }
+        else {
+            throw error;
+        }
+    }
+    return { name: Name };
+};
+export const getSettingsOptional = (args) => 
+/**
+ * In case of an unconfigured stack, returns default values
+ */
+async (defaultValue) => {
+    try {
+        return await getSettings(args)();
+    }
+    catch {
+        return defaultValue;
+    }
+};

package/dist/settings.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/settings.spec.js

@@ -0,0 +1,66 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { getSettingsOptional, settingsPath, getSettings } from './settings.js';
+void describe('getSettingsOptional()', () => {
+    void it('should return the given default value if parameter does not exist', async () => {
+        const stackConfig = getSettingsOptional({
+            ssm: {
+                send: async () => Promise.resolve({ Parameters: undefined }),
+            },
+            stackName: 'STACK_NAME',
+            scope: 'stack/context',
+        });
+        const result = await stackConfig({});
+        assert.deepEqual(result, {});
+    });
+});
+void describe('settingsPath()', () => {
+    void it('should produce a fully qualified parameter name', () => assert.equal(settingsPath({
+        scope: 'stack/context',
+        stackName: 'hello-nrfcloud',
+        property: 'someProperty',
+    }), '/hello-nrfcloud/stack/context/someProperty'));
+    void it('should produce a fully qualified parameter name for valid string scope', () => assert.equal(settingsPath({
+        scope: 'thirdParty/elite',
+        stackName: 'hello-nrfcloud',
+        property: 'someProperty',
+    }), '/hello-nrfcloud/thirdParty/elite/someProperty'));
+    void it('should error for invalid string scope', () => {
+        assert.throws(() => settingsPath({
+            scope: 'invalidScope',
+            stackName: 'hello-nrfcloud',
+            property: 'someProperty',
+        }));
+    });
+});
+void describe('getSettings()', () => {
+    void it('should return the object with same scope', async () => {
+        const returnedValues = [
+            {
+                Name: `/hello-nrfcloud/stack/context/key1`,
+                Value: 'value1',
+            },
+            {
+                Name: `/hello-nrfcloud/stack/context/key2`,
+                Value: 'value2',
+            },
+            {
+                Name: `/hello-nrfcloud/stack/context/key3`,
+                Value: 'value3',
+            },
+        ];
+        const stackConfig = getSettings({
+            ssm: {
+                send: async () => Promise.resolve({ Parameters: returnedValues }),
+            },
+            stackName: 'hello-nrfcloud',
+            scope: 'stack/context',
+        });
+        const result = await stackConfig();
+        assert.deepEqual(result, {
+            key1: 'value1',
+            key2: 'value2',
+            key3: 'value3',
+        });
+    });
+});

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@bifravst/aws-ssm-settings-helpers",
+  "version": "1.0.0",
+  "description": "Helper functions written in TypeScript for storing and retrieving application settings in AWS SSM Parameter Store.",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/settings.d.ts",
+        "default": "./dist/settings.js"
+      }
+    }
+  },
+  "type": "module",
+  "scripts": {
+    "test": "tsx --no-warnings --test ./src/*.spec.ts",
+    "prepare": "husky",
+    "prepublishOnly": "npx tsc --noEmit false --outDir ./dist -d"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bifravst/aws-ssm-settings-helpers.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bifravst/aws-ssm-settings-helpers/issues"
+  },
+  "homepage": "https://github.com/bifravst/aws-ssm-settings-helpers",
+  "keywords": [
+    "aws",
+    "ssm",
+    "typescript"
+  ],
+  "author": "Nordic Semiconductor ASA | nordicsemi.no",
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@bifravst/eslint-config-typescript": "6.0.17",
+    "@bifravst/prettier-config": "1.0.0",
+    "@commitlint/config-conventional": "19.1.0",
+    "@types/aws-lambda": "8.10.137",
+    "@types/node": "20.12.3",
+    "husky": "9.0.11",
+    "tsx": "4.7.2"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "prettier --write",
+      "eslint"
+    ],
+    "*.{md,json,yaml,yml}": [
+      "prettier --write"
+    ]
+  },
+  "engines": {
+    "node": ">=20",
+    "npm": ">=9"
+  },
+  "release": {
+    "branches": [
+      "saga",
+      {
+        "name": "!(saga)",
+        "prerelease": true
+      }
+    ],
+    "remoteTags": true,
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      [
+        "@semantic-release/github",
+        {
+          "successComment": false,
+          "failTitle": false
+        }
+      ]
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "package-lock.json",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "prettier": "@bifravst/prettier-config",
+  "peerDependencies": {
+    "@aws-sdk/client-ssm": "^3.549.0"
+  }
+}