@exabugs/dynamodb-client 0.2.2 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-01-20
+
+### Added
+
+- **Shadow Configuration**: Automatic field detection for all record types
+  - Support for 6 field types: string, number, boolean, datetime, array, object
+  - Automatic shadow generation for all fields in each record
+  - Environment variable-based configuration (4 variables)
+  - Comprehensive test suite (275 tests)
+  - Updated documentation with new configuration guide
+
+### Changed
+
+- **Shadow Configuration**: Simplified configuration management
+  - Replaced JSON configuration files with environment variables
+  - `SHADOW_CREATED_AT_FIELD` (default: `createdAt`)
+  - `SHADOW_UPDATED_AT_FIELD` (default: `updatedAt`)
+  - `SHADOW_STRING_MAX_BYTES` (default: `100`)
+  - `SHADOW_NUMBER_PADDING` (default: `15`)
+  - Primitive types truncated at 100 bytes
+  - Complex types (array/object) truncated at 200 bytes
+  - Number range: -10^15 to +10^15
+
+### Removed
+
+- **Shadow Configuration**: Removed schema-based configuration
+  - No longer requires `shadow.config.json` files
+  - No longer requires schema definitions for shadow fields
+  - Removed `generate-shadow-config` script
+  - Records are now independent and self-contained
+
+### Breaking Changes
+
+- **Shadow Configuration**: Configuration method has changed
+  - Old: JSON configuration files with schema definitions
+  - New: Environment variables with automatic field detection
+  - Migration: Set environment variables and remove JSON config files
+  - All fields are now automatically shadowed (no schema required)
+
 ## [0.2.2] - 2024-12-01
 
 ### Added

package/README.md

@@ -121,16 +121,22 @@ graph TB
 
 Get started in 3 steps: **Schema Definition → Deploy Infrastructure → Use Client**
 
-### Complete Examples Available
+### Complete Example Project
 
-We provide complete, working examples for every step:
+We provide a complete, working example project that demonstrates all features:
 
-| Example                                    | What You'll Learn                                    | Time   |
-| ------------------------------------------ | ---------------------------------------------------- | ------ |
-| **[Schema](./examples/schema/)**           | Define TypeScript schemas and generate shadow config | 5 min  |
-| **[Terraform](./examples/terraform/)**     | Deploy Lambda + DynamoDB + Cognito to AWS            | 10 min |
-| **[Client](./examples/client/)**           | Node.js CRUD operations with MongoDB-like API        | 10 min |
-| **[React Admin](./examples/react-admin/)** | Build complete admin UI with authentication          | 15 min |
+👉 **[dynamodb-client-example](https://github.com/exabugs/dynamodb-client-example)** - Full-stack example with React Admin
+
+This example includes:
+
+- ✅ Complete TypeScript schemas (Articles, Tasks)
+- ✅ Terraform infrastructure (DynamoDB, Lambda, Cognito)
+- ✅ React Admin UI with authentication
+- ✅ Shadow Records for efficient sorting
+- ✅ Production-ready configuration
+- ✅ Step-by-step QUICKSTART guide
+
+**Use it as a template** for your own projects!
 
 ### Quick Example
 
@@ -138,6 +144,7 @@ We provide complete, working examples for every step:
 // 1. Define schema
 export const MySchema: SchemaRegistryConfig = {
   database: {
+    name: 'myapp',
     timestamps: {
       createdAt: 'createdAt',
       updatedAt: 'updatedAt',
@@ -152,7 +159,7 @@ export const MySchema: SchemaRegistryConfig = {
   },
 };
 
-// 2. Deploy with Terraform (see examples/terraform/)
+// 2. Deploy with Terraform (see dynamodb-client-example)
 // terraform apply
 
 // 3. Use the client
@@ -163,16 +170,11 @@ await articles.insertOne({ title: 'Hello DynamoDB' });
 const article = await articles.findOne({ title: 'Hello DynamoDB' });
 ```
 
-### 📚 Full Documentation
-
-👉 **[Complete Examples Guide →](./examples/)** - Step-by-step tutorials with full source code
+### 📚 Getting Started
 
-Each example includes:
-
-- ✅ Complete source code
-- ✅ Step-by-step instructions
-- ✅ Terraform integration
-- ✅ Configuration templates
+1. **Clone the example project**: `git clone https://github.com/exabugs/dynamodb-client-example.git`
+2. **Follow the QUICKSTART guide**: See [QUICKSTART.md](https://github.com/exabugs/dynamodb-client-example/blob/main/QUICKSTART.md)
+3. **Customize for your needs**: Modify schemas, add resources, deploy to AWS
 
 ---
 
@@ -233,23 +235,85 @@ npm run clean         # Clean build artifacts
 
 ## 🚢 Deployment
 
-### Using Terraform
+### Using the Example Project
+
+The easiest way to deploy is using the [dynamodb-client-example](https://github.com/exabugs/dynamodb-client-example) project:
 
 ```bash
-cd terraform
-terraform init
-terraform plan -var-file=envs/dev.tfvars
-terraform apply -var-file=envs/dev.tfvars
+# Clone the example
+git clone https://github.com/exabugs/dynamodb-client-example.git
+cd dynamodb-client-example
+
+# Deploy to dev environment
+make deploy-dev
+
+# Deploy to other environments
+make deploy-stg    # Staging
+make deploy-prd    # Production
 ```
 
-### Using Make
+See the [example project's documentation](https://github.com/exabugs/dynamodb-client-example) for detailed deployment instructions.
 
-```bash
-make deploy-dev    # Deploy to dev environment
-make deploy-stg    # Deploy to staging
-make deploy-prd    # Deploy to production
+---
+
+## 🔧 Shadow Configuration
+
+### Overview
+
+The shadow feature automatically makes all fields sortable without requiring JSON configuration files. Configuration is managed entirely through environment variables.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHADOW_CREATED_AT_FIELD` | `createdAt` | Field name for creation timestamp |
+| `SHADOW_UPDATED_AT_FIELD` | `updatedAt` | Field name for update timestamp |
+| `SHADOW_STRING_MAX_BYTES` | `100` | Max bytes for primitive types (array/object use 2x) |
+| `SHADOW_NUMBER_PADDING` | `15` | Padding digits for numbers |
+
+### Supported Types
+
+- **string**: Strings (truncated at 100 bytes)
+- **number**: Numbers (offset method, range: -10^15 to +10^15)
+- **boolean**: Booleans (true=1, false=0)
+- **datetime**: ISO 8601 datetime strings
+- **array**: Arrays (JSON stringified, truncated at 200 bytes)
+- **object**: Objects (JSON stringified, truncated at 200 bytes)
+
+### Automatic Shadow Generation
+
+Only fields that exist in each record are automatically shadowed:
+
+```typescript
+const record = {
+  id: '01HQXYZ123',
+  title: 'Article',
+  viewCount: 123,
+  published: true,
+  tags: ['tech', 'aws'],
+  metadata: { category: 'tech' }
+};
+
+// Automatically generates shadow records:
+// - id#01HQXYZ123#id#01HQXYZ123
+// - title#Article#id#01HQXYZ123
+// - viewCount#1000000000000123#id#01HQXYZ123
+// - published#1#id#01HQXYZ123
+// - tags#["aws","tech"]#id#01HQXYZ123
+// - metadata#{"category":"tech"}#id#01HQXYZ123
 ```
 
+### Exclusion Rules
+
+- Fields starting with `__` are excluded (internal metadata)
+- `null` or `undefined` values are excluded
+
+### Important Notes
+
+- Records without a specific field won't appear in sort results for that field
+- Primitive types are truncated at 100 bytes, complex types at 200 bytes
+- Number range is -10^15 to +10^15 (within JavaScript's safe integer range)
+
 ---
 
 ## 🤝 Contributing

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export type { Logger, LoggerConfig, LogLevel, LogMetadata } from './logger.js';
 export { ErrorCode, AppError, AuthError, ConfigError, InvalidFilterError, InvalidTokenError, ItemNotFoundError, PartialFailureError, VersionConflictError, isAppError, getErrorClass, } from './errors.js';
 export type { FilterOperators, Filter, UpdateOperators, FindOptions, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, } from './types.js';
 export { Database, Collection } from './client/index.js';
-export { convertFilterToDynamo, type DynamoComparisonOperator, type DynamoCondition, type DynamoQuery, generateShadowRecords, type ShadowRecord, type ShadowSchema, getShadowConfig, getResourceSchema, clearShadowConfigCache, type ShadowConfig, } from './server/index.js';
+export { convertFilterToDynamo, type DynamoComparisonOperator, type DynamoCondition, type DynamoQuery, generateShadowRecords, type ShadowRecord, getShadowConfig, clearShadowConfigCache, type ShadowConfig, } from './server/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,MAAM,EACN,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,MAAM,EACN,eAAe,EACf,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,qBAAqB,EACrB,KAAK,YAAY,EACjB,eAAe,EACf,sBAAsB,EACtB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -3,5 +3,5 @@ export { ulid, ulidWithTime, decodeTime } from './ulid.js';
 export { createLogger } from './logger.js';
 export { ErrorCode, AppError, AuthError, ConfigError, InvalidFilterError, InvalidTokenError, ItemNotFoundError, PartialFailureError, VersionConflictError, isAppError, getErrorClass, } from './errors.js';
 export { Database, Collection } from './client/index.js';
-export { convertFilterToDynamo, generateShadowRecords, getShadowConfig, getResourceSchema, clearShadowConfigCache, } from './server/index.js';
+export { convertFilterToDynamo, generateShadowRecords, getShadowConfig, clearShadowConfigCache, } from './server/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAC;AAarB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EACL,qBAAqB,EAIrB,qBAAqB,EAGrB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,aAAa,GACd,MAAM,aAAa,CAAC;AAarB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EACL,qBAAqB,EAIrB,qBAAqB,EAErB,eAAe,EACf,sBAAsB,GAEvB,MAAM,mBAAmB,CAAC"}