Release notes v0.0.212

The major breaking change for this Compas release is the refactoring of file related functions, including a swap from the Minio JS SDK to the AWS S3 SDK.

This was done for a couple of reasons. The file related functions where all over the place with no consistent names. Now they are all prefixed with either objectStorage or file(Send) and accept their arguments with consistent order and naming. Another reason is that the AWS SDK is somewhat lighter and since V3 has a pretty nice api to work with. Making it much easier to use the same AWS client for all your projects needs.

Below we will try to be as exhaustive as possible with all the breaking changes. Most of them should be fixable by calling a different function or providing different arguments. Most of the functionality stays the same.

Upgrade path

Environment variables:

The MINIO_ environment variables are not read anymore by Compas. For development, you should use the objectStorageGetDevelopmentConfig() function to connect with the local Minio container. For production, you should refer to the AWS SDK docs about credentials .

newMinioClient() -> objectStorageCreateClient():

Creating a client now looks something like the following;

const s3Client = objectStorageCreateClient(
  isProduction()
    ? {
        /* See AWS SDK docs */
      }
    : objectStorageGetDevelopmentConfig(),
);

MinioClient -> S3Client:

The MinioClient type is also removed. Compas is now typed with the S3Client type. This can be imported from @compas/store or is generated as a global type via app#generateTypes({ dumpCompasTypes: true }) from @compas/code-gen.

ensureBucket() -> objectStorageEnsureBucket():

ensureBucket is replaced with objectStorageEnsureBucket.

removeBucket() / removeBucketAndObjectsInBucket() -> objectStorageRemoveBucket():

Both removeBucket and removeBucketAndObjectsInBucket are consolidated in to a single function. Note that this may be a slow operation depending on how many objects there are.

listObjects() -> objectStorageListObjects()

A notable change here is that instead of returning an array with keys, it now returns an AsyncIterator, this can be used like so;

for await (const partition of objectStorageListObjects(s3Client, {
  bucketName,
})) {
  for (const object of partition?.Contents ?? []) {
    // -> object.Key
  }
}

copyAllObjects() / copyFile():

These copy operations are now longer supported. Use the AWS SDK directly via the CopyObjectCommand .

createOrUpdateFile() -> fileCreateOrUpdate():

This is not only a rename, but the function signature has changed as well. The bucketName and options (last argument) are consolidated in to a single options object. Otherwise the working is the same.

fileFormatResponse() -> fileFormatMetadata():

The api is the same, but merely renamed to avoid confusion with fileSendResponse. Since this function does not return a response but only an object.

getFileStream() -> objectStorageGetObjectStream():

This function has an api change to align with the other exported functions.

syncDeletedFiles() -> fileSyncDeletedWithObjectStorage():

Another function that is renamed and has some renamed arguments for consistency.

FileCache:

The FileCache is removed. It's functionality was questionable at best. Later versions may bring this kind of functionality back, but in another form. Compas functions that expected an getStreamFn are now changed to just expect the S3Client directly.

sendFile() -> fileSendResponse():

The sendFile utility from @compas/server is removed and replaced with fileSendResponse() from @compas/store. This brings all file handling in to @compas/store where it belongs. The functionality is however the same as before.

sendTransformedImage() -> fileSendTransformedImageResponse():

Other than the rename, this function now doesn't accept sendFile anymore. This was necessary before because sendFile was not part of @compas/store.

create-compas

Another main addition this release cycle is the experimental create-compas package. Initialize Compas projects based on Compas examples or a custom repository.

Examples:

  • yarn create compas
  • npx create-compas@latest
  • npx create-compas@latest --template with-auth
  • npx create-compas@latest --template github:user/repo --output-directory ./my-project
  • npx create-compas@latest --template github:user/repo --template-path ./path/to/scaffold --template-ref v1.0

Note that we are currently working on the default template, so npx create-compas@latest currently only creates a project with the necessary configuration for @compas/eslint-plugin. Feel free to sometimes create the template from main via npx create-compas@latest --template-ref main to see the work in progress.

In closing

The file handling functionality always stood out from the rest. Being the main source of api inconsistencies. With this refactor most functionality is kept as is and unused or questionable functionality is removed. I hope you have a smooth upgrade! Feel free to leave feedback on a GitHub issue or discussion.