@ez4/database 0.35.0 → 0.36.0

package/README.md

@@ -1,15 +1,132 @@
 # EZ4: Database
 
-It uses the power of [reflection](../reflection/) to provide an API which determines how to build and connect database components.
+It uses the power of [reflection](../../foundation/reflection/) to provide a contract that determines how to build and connect database components.
 
 ## Getting started
 
 #### Install
 
 ```sh
-npm install @ez4/database -D
+npm install @ez4/database @ez4/local-database @ez4/aws-aurora -D
 ```
 
+> You can use `@ez4/aws-dynamodb` instead of `@ez4/aws-aurora` for NoSQL database.
+
+#### Create database
+
+```ts
+// file: db.ts
+import type { Environment, Service } from '@ez4/common';
+import type { Database } from '@ez4/database';
+
+// MyDb message
+type MyTableSchema = {
+  foo: string;
+  bar: number;
+};
+
+// MyDb declaration
+export declare class MyDb extends Database.Service {
+  client: Client<Db>;
+
+  engine: PostgresEngine;
+
+  tables: [
+    Database.UseTable<{
+      name: 'my_table';
+      schema: MyTableSchema;
+      indexes: {
+        foo: Index.Primary;
+      };
+    }>
+  ];
+}
+```
+
+#### Use database
+
+```ts
+// file: handler.ts
+import type { Service } from '@ez4/common';
+import type { MyDb } from './db';
+
+// Any other handler that has injected MyDb service
+export async function anyHandler(_request: any, context: Service.Context<DummyService>) {
+  const { MyDb } = context;
+
+  // Insert one record
+  await MyDb.my_table.insertOne({
+    data: {
+      foo: 'foo',
+      bar: 123
+    }
+  });
+
+  // Find one record
+  const result = await MyDb.my_table.findOne({
+    select: {
+      bar: true
+    },
+    where: {
+      foo: 'foo'
+    }
+  });
+}
+```
+
+## Database properties
+
+#### Service
+
+| Name        | Type                      | Description                                      |
+| ----------- | ------------------------- | ------------------------------------------------ |
+| scalability | Database.UseScalability<> | Scalability configuration.                       |
+| tables      | Database.UseTable<>       | Describe all available tables for the service.   |
+| engine      | object                    | Determines which database engine to use.         |
+| variables   | object                    | Environment variables associated to all streams. |
+| services    | object                    | Injected services associated to all streams.     |
+
+> Use type helpers for `scalability` and `tables` properties.
+
+#### Tables
+
+| Name      | Type                      | Description                 |
+| --------- | ------------------------- | --------------------------- |
+| stream    | Database.UseTableStream<> | Table stream configuration. |
+| name      | string                    | Table name.                 |
+| schema    | object                    | Table schema.               |
+| relations | object                    | Table relations.            |
+| indexes   | object                    | Table indexes.              |
+
+#### Streams (DynamoDB)
+
+| Name         | Type     | Description                                      |
+| ------------ | -------- | ------------------------------------------------ |
+| listener     | function | Life-cycle listener function for the stream.     |
+| handler      | function | Entry-point handler function for the stream.     |
+| variables    | object   | Environment variables associated to the stream.  |
+| logRetention | integer  | Log retention (in days) for the handler.         |
+| memory       | integer  | Memory available (in megabytes) for the handler. |
+| timeout      | integer  | Max execution time (in seconds) for the route.   |
+
+> Streams is a DynamoDB feature, thus unavailable for Aurora Postgres.
+
+## Examples
+
+- [Get started with Aurora RDS](../../examples/hello-aws-aurora)
+- [Get started with DynamoDB](../../examples/hello-aws-dynamodb)
+- [Aurora RDS CRUDL](../../examples/aws-aurora-crudl)
+- [DynamoDB CRUDL](../../examples/aws-dynamodb-crudl)
+- [DynamoDB streams](../../examples/aws-dynamodb-streams)
+- [Schedule manager](../../examples/aws-schedule-manager)
+- [Storage manager](../../examples/aws-storage-manager)
+
+## Providers
+
+- [Local provider](../../providers/local/local-database)
+- [AWS Aurora provider](../../providers/aws/aws-aurora)
+- [AWS DynamoDB provider](../../providers/aws/aws-dynamodb)
+
 ## License
 
 MIT License

package/dist/main.cjs

@@ -1,6 +1,6 @@
-"use strict";var o=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var S=(n,a)=>{for(var e in a)o(n,e,{get:a[e],enumerable:!0})},g=(n,a,e,r)=>{if(a&&
-typeof a=="object"||typeof a=="function")for(let t of I(a))!u.call(n,t)&&t!==e&&
-o(n,t,{get:()=>a[t],enumerable:!(r=b(a,t))||r.enumerable});return n};var f=n=>g(o({},"__esModule",{value:!0}),n);var D={};S(D,{Database:()=>y,Index:()=>c,InsensitiveMode:()=>m,LockMode:()=>x,Order:()=>l,
+"use strict";var o=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var S=Object.prototype.hasOwnProperty;var u=(n,a)=>{for(var e in a)o(n,e,{get:a[e],enumerable:!0})},g=(n,a,e,r)=>{if(a&&
+typeof a=="object"||typeof a=="function")for(let t of I(a))!S.call(n,t)&&t!==e&&
+o(n,t,{get:()=>a[t],enumerable:!(r=b(a,t))||r.enumerable});return n};var f=n=>g(o({},"__esModule",{value:!0}),n);var D={};u(D,{Database:()=>y,Index:()=>c,InsensitiveMode:()=>m,LockMode:()=>x,Order:()=>l,
 OrderMode:()=>T,PaginationMode:()=>d,ParametersMode:()=>p,StreamChangeType:()=>s,
 TransactionMode:()=>i});module.exports=f(D);var s=(r=>(r.Insert="insert",r.Update="update",r.Delete="delete",r))(s||{});var p=(e=>(e.NameAndIndex="both",e.OnlyIndex="index",e))(p||{});var i=(e=>(e.Interactive="interactive",e.Static="static",e))(i||{});var m=(e=>(e.Unsupported="unsupported",e.Enabled="enabled",e))(m||{});var d=(e=>(e.Cursor="cursor",e.Offset="offset",e))(d||{});var l=(e=>(e.Asc="asc",e.Desc="desc",e))(l||{}),T=(e=>(e.IndexColumns="index",e.
 AnyColumns="any",e))(T||{});var x=(e=>(e.Unsupported="unsupported",e.Supported="supported",e))(x||{});var y;(n=>{})(y||={});var c=(t=>(t.Primary="primary",t.Secondary="secondary",t.Unique="unique",t.TTL="\

package/dist/services/contract.d.ts

@@ -36,6 +36,10 @@ export declare namespace Database {
      * Database Scalability definition.
      */
     type UseScalability<T extends DatabaseScalability> = T;
+    /**
+     * Database Table stream definition.
+     */
+    type UseTableStream<T extends Stream<any>> = T;
     /**
      * Database service.
      */

package/dist/services/query.d.ts

@@ -96,8 +96,17 @@ export declare namespace Query {
         order?: StrictIncludeOrder<V>;
     };
     export type WhereInput<T extends TableMetadata, I extends boolean = false> = Prettify<WhereInputFilters<T, I extends true ? T['indexes'] : {}> & {
+        /**
+         * Check whether the expression is not true.
+         */
         NOT?: WhereInput<T>;
+        /**
+         * Check whether all the expressions are true.
+         */
         AND?: WhereInput<T>[];
+        /**
+         * Check whether any of all the expressions are true.
+         */
         OR?: WhereInput<T>[];
     }>;
     type SelectInputFields<T extends Database.Schema, R extends RelationMetadata> = IsObjectEmpty<R['selects']> extends true ? T : T & R['selects'];
@@ -108,8 +117,17 @@ export declare namespace Query {
         [P in keyof V]?: WhereField<V[P], E>;
     };
     type WhereRelationField<V extends AnyObject, E extends DatabaseEngine> = WhereObjectField<V, E> & {
+        /**
+         * Check whether the expression is not true.
+         */
         NOT?: WhereRelationField<V, E>;
+        /**
+         * Check whether all the expressions are true.
+         */
         AND?: WhereRelationField<V, E>[];
+        /**
+         * Check whether any of all the expressions are true.
+         */
         OR?: WhereRelationField<V, E>[];
     };
     type WhereRelationFilters<V extends AnyObject, E extends DatabaseEngine> = {
@@ -128,39 +146,75 @@ export declare namespace Query {
     type WhereInputFilters<T extends TableMetadata, I extends Database.Indexes> = WhereCommonFilters<T['schema'], T, I> & (IsObjectEmpty<T['relations']['filters']> extends false ? WhereRelationFilters<T['relations']['filters'], T['engine']> : {});
     export type WhereOperators = keyof (WhereNegate<any, never> & WhereEqual<any, never> & WhereGreaterThan<any> & WhereGreaterThanOrEqual<any> & WhereLessThan<any> & WhereLessThanOrEqual<any> & WhereIn<any> & WhereBetween<any> & WhereIsMissing & WhereIsNull & WhereStartsWith<never> & WhereContains<any, never>);
     type WhereNegate<V, E extends DatabaseEngine> = (V extends string ? InsensitiveModeUtils.Input<E> : {}) & {
+        /**
+         * Check whether the entity value is not equal to the given one.
+         */
         not: V;
     };
     type WhereEqual<V, E extends DatabaseEngine> = (V extends string ? InsensitiveModeUtils.Input<E> : {}) & {
+        /**
+         * Check whether the entity value is equal to the given one.
+         */
         equal: V;
     };
     type WhereGreaterThan<V> = {
+        /**
+         * Check whether the entity value is greater than the given one.
+         */
         gt: V;
     };
     type WhereGreaterThanOrEqual<V> = {
+        /**
+         * Check whether the entity value is greater than or equal the given one.
+         */
         gte: V;
     };
     type WhereLessThan<V> = {
+        /**
+         * Check whether the entity value is less than the given one.
+         */
         lt: V;
     };
     type WhereLessThanOrEqual<V> = {
+        /**
+         * Check whether the entity value is less than or equal the given one.
+         */
         lte: V;
     };
     type WhereIn<V> = {
+        /**
+         * Check whether the entity value is in the given ones.
+         */
         isIn: IsArray<V> extends true ? V : IsObject<V> extends true ? V : Exclude<V, undefined>[];
     };
     type WhereBetween<V> = {
+        /**
+         * Check whether the entity value is between the given ones.
+         */
         isBetween: [Exclude<V, undefined>, Exclude<V, undefined>];
     };
     type WhereIsMissing = {
+        /**
+         * Check whether the entity value is missing.
+         */
         isMissing: boolean;
     };
     type WhereIsNull = {
+        /**
+         * Check whether the entity value is null.
+         */
         isNull: boolean;
     };
     type WhereStartsWith<E extends DatabaseEngine> = InsensitiveModeUtils.Input<E> & {
+        /**
+         * Check whether the entity value starts with the given one.
+         */
         startsWith: string;
     };
     type WhereContains<V, E extends DatabaseEngine> = (V extends string ? InsensitiveModeUtils.Input<E> : {}) & {
+        /**
+         * Check whether the entity value contains all the given ones.
+         */
         contains: IsObject<V> extends true ? Partial<V> : V;
     };
     export type AtomicOperators = keyof (AtomicIncrement & AtomicDecrement & AtomicMultiply & AtomicDivide);
@@ -174,15 +228,27 @@ export declare namespace Query {
     };
     type AtomicOperation = AtomicIncrement | AtomicDecrement | AtomicMultiply | AtomicDivide;
     type AtomicIncrement = {
+        /**
+         * Increment the entity value by the given amount.
+         */
         increment: number;
     };
     type AtomicDecrement = {
+        /**
+         * Decrement the entity value by the given amount.
+         */
         decrement: number;
     };
     type AtomicMultiply = {
+        /**
+         * Multiply the entity value by the given amount.
+         */
         multiply: number;
     };
     type AtomicDivide = {
+        /**
+         * Divide the entity value by the given amount.
+         */
         divide: number;
     };
     export {};

package/dist/services/streams.d.ts

@@ -6,11 +6,11 @@ import type { TableSchema } from './schemas';
  */
 export interface TableStream<T extends TableSchema> {
     /**
-     * Stream listener.
+     * Life-cycle listener function for the stream.
      */
     readonly listener?: TableStreamListener<T>;
     /**
-     * Stream handler.
+     * Entry-point handler function for the stream.
      */
     readonly handler: TableStreamHandler<T>;
     /**
@@ -26,7 +26,7 @@ export interface TableStream<T extends TableSchema> {
      */
     readonly timeout?: number;
     /**
-     * Amount of memory available for the handler.
+     * Amount of memory available (in megabytes) for the handler.
      */
     readonly memory?: number;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ez4/database",
   "description": "EZ4: Components to build database services",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "author": "Silas B.",
   "license": "MIT",
   "type": "module",
@@ -46,10 +46,10 @@
     "live:publish": "npm run build && npm publish --access public"
   },
   "dependencies": {
-    "@ez4/common": "^0.35.0",
-    "@ez4/project": "^0.35.0",
-    "@ez4/reflection": "^0.35.0",
-    "@ez4/schema": "^0.35.0",
-    "@ez4/utils": "^0.35.0"
+    "@ez4/common": "^0.36.0",
+    "@ez4/project": "^0.36.0",
+    "@ez4/reflection": "^0.36.0",
+    "@ez4/schema": "^0.36.0",
+    "@ez4/utils": "^0.36.0"
   }
 }

package/dist/services/database.d.ts

@@ -1,142 +0,0 @@
-import type { Service as CommonService } from '@ez4/common';
-import type { LinkedVariables } from '@ez4/project/library';
-import type { StreamChange } from './streams';
-import type { DatabaseEngine } from './engine';
-import type { Client } from './client';
-/**
- * Given a database service `T`, it returns all its table.
- */
-export type DatabaseTables<T> = T extends {
-    tables: infer U;
-} ? U : [];
-/**
- * Provide all contracts for a self-managed database service.
- */
-export declare namespace Database {
-    /**
-     * Table schema.
-     */
-    interface Schema {
-    }
-    /**
-     * Table relations.
-     */
-    interface Relations {
-    }
-    /**
-     * Table indexes.
-     */
-    type Indexes = {};
-    /**
-     * Incoming stream event.
-     */
-    type Incoming<T extends Schema> = StreamChange<T> & Request;
-    /**
-     * Incoming request.
-     */
-    type Request = {
-        /**
-         * Request tracking Id.
-         */
-        requestId: string;
-    };
-    /**
-     * Stream listener.
-     */
-    type Listener<T extends Schema> = (event: CommonService.AnyEvent<Incoming<T>>, context: CommonService.Context<Database.Service>) => Promise<void> | void;
-    /**
-     * Stream handler.
-     */
-    type Handler<T extends Schema> = (request: Incoming<T>, context: CommonService.Context<Database.Service>) => Promise<void> | void;
-    /**
-     * Service event.
-     */
-    type ServiceEvent<T extends Schema = Schema> = CommonService.BeginEvent<Request> | CommonService.ReadyEvent<Incoming<T>> | CommonService.DoneEvent<Incoming<T>> | CommonService.ErrorEvent<Request | Incoming<T>> | CommonService.EndEvent<Request>;
-    /**
-     * Service engine.
-     */
-    type Engine = DatabaseEngine;
-    /**
-     * Service scalability configuration.
-     */
-    interface Scalability {
-        minCapacity: number;
-        maxCapacity: number;
-    }
-    /**
-     * Table stream.
-     */
-    interface Stream<T extends Schema = Schema> {
-        /**
-         * Stream listener.
-         */
-        listener?: Listener<T>;
-        /**
-         * Stream handler.
-         */
-        handler: Handler<T>;
-        /**
-         * Variables associated to the handler.
-         */
-        variables?: LinkedVariables;
-        /**
-         * Log retention (in days) for the handler.
-         */
-        logRetention?: number;
-        /**
-         * Max execution time (in seconds) for the handler.
-         */
-        timeout?: number;
-        /**
-         * Amount of memory available for the handler.
-         */
-        memory?: number;
-    }
-    /**
-     * Database table.
-     */
-    interface Table<T extends Schema = Schema> {
-        /**
-         * Table name.
-         */
-        name: string;
-        /**
-         * Table schema.
-         */
-        schema: T;
-        /**
-         * Table relations.
-         */
-        relations?: Relations;
-        /**
-         * Table indexes.
-         */
-        indexes: Indexes;
-        /**
-         * Table stream configuration.
-         */
-        stream?: Stream<T>;
-    }
-    /**
-     * Database service.
-     */
-    abstract class Service implements CommonService.Provider {
-        /**
-         * Determines which database engine to use.
-         * Check the provider package to know all the possible values.
-         */
-        abstract engine: Engine;
-        /**
-         * Describe all available tables for the service.
-         */
-        abstract tables: Table<any>[];
-        /**
-         * Scalability configuration.
-         */
-        scalability: Scalability;
-        /**
-         * Service client.
-         */
-        client: Client<Service>;
-    }
-}