@stacksjs/storage 0.70.332 → 0.70.333

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { ProvisionOptions, ProvisionResult } from './provision';
 export type { ServeFileOptions } from './static-serve';
 export type { DiskConfig, FilesystemConfig, LocalDiskConfig, S3DiskConfig } from './facade';
 export type { FilenameStrategy, PutFileOptions, UploadedFileLike } from './put-file';
@@ -26,6 +27,7 @@ export * from './hash';
 export * from './helpers';
 export * as storage from './storage';
 export * from './zip';
+export { ensureBucket, ensureConfiguredBuckets } from './provision';
 // Storage adapters and types
 export * from './adapters/index';
 export * from './types';

package/dist/index.js

@@ -1 +1 @@
-export*from"./copy";export*from"./delete";export*from"./files";export*from"./folders";export*from"./fs";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{backblazeDisk,configFromEnv,filebaseDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";
+export*from"./copy";export*from"./delete";export*from"./files";export*from"./folders";export*from"./fs";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export{ensureBucket,ensureConfiguredBuckets}from"./provision";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{backblazeDisk,configFromEnv,filebaseDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";

package/dist/provision.d.ts

@@ -0,0 +1,45 @@
+import type { ObjectStorageProvider } from '@stacksjs/ts-cloud';
+/**
+ * Make sure `bucket` exists, creating it if it does not.
+ *
+ * Idempotent: an existing bucket is reported rather than treated as an error,
+ * so this is safe to call on every deploy and on every boot.
+ */
+export declare function ensureBucket(bucket: string, options?: ProvisionOptions): Promise<ProvisionResult>;
+/**
+ * Ensure every bucket the app's filesystem config names.
+ *
+ * Reads `filesystems.s3.bucket` plus any bucket named by a configured disk, so
+ * a deploy provisions what the app is actually configured to use rather than a
+ * list maintained separately.
+ */
+export declare function ensureConfiguredBuckets(options?: ProvisionOptions): Promise<ProvisionResult[]>;
+/**
+ * Bucket provisioning.
+ *
+ * An app that writes to object storage should not fail on its first upload
+ * because nobody created the bucket by hand, and it should not require a
+ * separate infrastructure step for something the app already knows the name of.
+ * Vapor provisions the bucket as part of deploying; this is the same idea,
+ * available both as an explicit call and as an on-demand check before a write.
+ *
+ * Creation is deliberately *not* implicit on every write. `ensureBucket` is
+ * cheap but not free, and silently creating buckets from a typo'd config name
+ * is how an account ends up with a dozen near-identical buckets and data
+ * spread across them. Apps opt in via `filesystems.autoCreateBuckets`.
+ */
+export declare interface ProvisionOptions {
+  provider?: ObjectStorageProvider
+  region?: string
+  endpoint?: string
+  credentials?: { accessKeyId: string, secretAccessKey: string }
+  acl?: string
+}
+export declare interface ProvisionResult {
+  bucket: string
+  status: 'created' | 'exists'
+  provider: ObjectStorageProvider
+  region: string
+  endpoint?: string
+  publicUrl: string
+}

package/dist/provision.js

@@ -0,0 +1 @@
+export async function ensureBucket(bucket,options={}){if(!bucket)throw Error("ensureBucket requires a bucket name.");const{createObjectStorageClient,resolveObjectStorage}=await import("@stacksjs/ts-cloud"),resolved=resolveObjectStorage(options),client=createObjectStorageClient(options),base={bucket,provider:resolved.provider,region:resolved.region,endpoint:resolved.endpoint,publicUrl:resolved.publicBaseUrl(bucket)};if(await client.bucketExists(bucket))return{...base,status:"exists"};try{await client.createBucket(bucket,{acl:options.acl??"private"});return{...base,status:"created"}}catch(error){const message=error instanceof Error?error.message:String(error);if(/BucketAlreadyOwnedByYou|BucketAlreadyExists|already exists/i.test(message))return{...base,status:"exists"};throw Error(`Could not create bucket "${bucket}" on ${resolved.provider}: ${message}`)}}export async function ensureConfiguredBuckets(options={}){const{filesystems}=await import("@stacksjs/config"),names=new Set;if(filesystems?.s3?.bucket)names.add(filesystems.s3.bucket);for(const disk of Object.values(filesystems?.disks??{})){const candidate=disk;if(candidate?.driver==="s3"&&candidate.bucket)names.add(candidate.bucket)}if(names.size===0)return[];const results=[];for(const name of names)results.push(await ensureBucket(name,options));return results}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/storage",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.332",
+  "version": "0.70.333",
   "description": "The Stacks file system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -65,11 +65,11 @@
     "ts-images": "^0.2.8"
   },
   "devDependencies": {
-    "@stacksjs/arrays": "0.70.332",
+    "@stacksjs/arrays": "0.70.333",
     "better-dx": "^0.2.17",
-    "@stacksjs/error-handling": "0.70.332",
-    "@stacksjs/path": "0.70.332",
-    "@stacksjs/strings": "0.70.332",
-    "@stacksjs/types": "0.70.332"
+    "@stacksjs/error-handling": "0.70.333",
+    "@stacksjs/path": "0.70.333",
+    "@stacksjs/strings": "0.70.333",
+    "@stacksjs/types": "0.70.333"
   }
 }