Registry / storage / oc-s3-storage-adapter

oc-s3-storage-adapter

library2.2.2jsnpmunverified

S3 storage adapter for OC (OpenComponents), enabling S3-compatible storage backends for OC registries. Current stable version 2.2.2 integrates with OC v1.x registries. Provides an adapter class implementing the OC storage interface to store and retrieve components and templates from AWS S3 or compatible services (e.g., MinIO). Key differentiator: minimal configuration, built-in retry and error handling, and supports modern S3 features like server-side encryption. Release cadence is ad-hoc, typically with bug fixes and compatibility updates. TypeScript definitions included.

storage devops

npm install oc-s3-storage-adapter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OC-S3-STORAGE-ADAP

oc-s3-storage-adapter

storagejavascriptv2.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

S3StorageAdapter

✓ import { S3StorageAdapter } from 'oc-s3-storage-adapter'

✗ const S3StorageAdapter = require('oc-s3-storage-adapter').S3StorageAdapter

Named export; types included. For CommonJS, use require and destructure.

default

✓ import S3Adapter from 'oc-s3-storage-adapter'

✗ const S3Adapter = require('oc-s3-storage-adapter')

Default export available; the module exports both default and named export. CommonJS require returns the default export.

S3Config

✓ import type { S3Config } from 'oc-s3-storage-adapter'

✗ import { S3Config } from 'oc-s3-storage-adapter' (if value import not intended)

TypeScript type export; can be imported as type-only to avoid runtime impact.

Initializes S3StorageAdapter with an S3 client and bucket, then uses it as storage for an OC registry.

import { S3StorageAdapter } from 'oc-s3-storage-adapter'; import S3 from 'aws-sdk/clients/s3'; const s3Client = new S3({ region: 'us-east-1', accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', }); const adapter = new S3StorageAdapter({ s3Client, bucket: 'my-oc-components', keyPrefix: 'components/', }); // Use adapter with OC registry const registry = new OC.Registry({ storage: adapter });

Debug

Known issues

gotchaThe adapter expects an S3 client instance (aws-sdk v2), not configuration object. Passing a config object will fail silently or cause runtime error.

fix

Create an S3 client via `new AWS.S3({...})` and pass it as `s3Client` option.

affects: >=1.0.0

deprecatedaws-sdk v2 is used; aws-sdk v3 (modular) is not supported. The class internally uses v2 methods like `.getObject().promise()`.

fix

Install aws-sdk v2 and ensure no v3 client is passed. Migrate to v3 only after adapter is updated.

affects: >=2.0.0

gotchaIf `keyPrefix` does not end with a slash, component paths may be misconstructed (e.g., 'componentsmy-component').

fix

Always append a trailing slash to keyPrefix, e.g., 'components/'.

affects: >=1.0.0

breakingVersion 2.0.0 changed the constructor from taking a single config object to requiring `s3Client` and `bucket` as separate options. Old code passing raw S3 constructor options will break.

fix

Update constructor call: `new S3StorageAdapter({ s3Client: new AWS.S3({...}), bucket: '...' })`.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'promise')

aws-sdk v2 method .promise() is called on a non-request object, possible due to passing v3 client or config object instead of S3 instance.

fix

Ensure you pass an instance of AWS.S3 from aws-sdk v2, e.g., `new AWS.S3({apiVersion: '2006-03-01'})`.

Error: Unknown options: s3Client

Using pre-2.0.0 API where constructor expected configuration object; passing `s3Client` as a property of the config is invalid.

fix

Upgrade to adapter v2+ and pass `s3Client` as a top-level option directly: `new S3StorageAdapter({ s3Client, bucket })`.

AccessDenied: Access Denied

S3 credentials lack permissions to list objects or read from the specified bucket/prefix.

fix

Verify IAM policy: must allow s3:ListBucket, s3:GetObject, and s3:PutObject on the bucket and prefix.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

ocrequiredPeer dependency; requires OC registry runtime to function

aws-sdkrequiredRequired to interact with S3 API

Agent activity

31 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/opencomponents/storage-adapters ↗

packageoc-s3-storage-adapter ↗

homepagehttps://github.com/opencomponents/storage-adapters#readme ↗