akanjs 0.0.1 → 2.0.0-beta.1

package/cli/guidelines/scalarConstant/scalarConstant.generate.json

@@ -0,0 +1,106 @@
+{
+  "title": "Scalar Constant",
+  "description": "how to generate a scalar.constant.ts file",
+  "scans": [
+    {
+      "type": "source",
+      "description": "core constant library source code for scalar definitions",
+      "path": "pkgs/akanjs/constant/classMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "field metadata implementation",
+      "path": "pkgs/akanjs/constant/fieldMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "via() function and scalar implementation",
+      "path": "pkgs/akanjs/constant/baseGql.ts"
+    },
+    {
+      "type": "source",
+      "description": "base scalar types and enumOf implementation",
+      "path": "pkgs/akanjs/base/base.ts"
+    },
+    {
+      "type": "source",
+      "description": "GqlScalar type definition",
+      "path": "pkgs/akanjs/base/scalar.ts"
+    },
+    {
+      "type": "source",
+      "description": "constant metadata usage in graphql schema generation",
+      "path": "pkgs/akanjs/server/gql.ts"
+    },
+    {
+      "type": "source",
+      "description": "constant metadata usage in mongoDB schema generation",
+      "path": "pkgs/akanjs/server/schema.ts"
+    },
+    {
+      "type": "example",
+      "description": "simple scalar.constant.ts file examples",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "lines < 30",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "complex scalar.constant.ts file examples with enum definitions",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "lines > 30 && /enumOf/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "scalar.constant.ts file examples with static methods",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "/static\\s+\\w+/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "scalar.constant.ts file examples with nested scalar references",
+      "path": "{apps,libs}/*/lib/__scalar/*/*.constant.ts",
+      "query": "/import.*\\.constant/",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./scalarConstant.instruction.md",
+    "contents": [
+      "Purpose of scalar constants in Akan.js",
+      "File structure and location conventions",
+      "Naming standards for directories, files, classes and enums",
+      "Required imports from akanjs/constant and akanjs/base",
+      "Basic syntax with via() function",
+      "Field definitions with field() helper function",
+      "Field options reference table (default, min, max, minlength, maxlength, validate, example)",
+      "Available field types (String, Int, Float, Boolean, Date, ID)",
+      "Array fields using bracket notation [Type]",
+      "Optional fields using .optional() chain method",
+      "Enum definition with enumOf(name, values) class pattern",
+      "Instance methods in scalar classes",
+      "Static methods in scalar classes",
+      "Common mistakes and fixes",
+      "Implementation checklist",
+      "Full examples of scalar.constant.ts files"
+    ],
+    "rules": [
+      "One scalar.constant.ts should contain only one scalar class extending via(). If you need more than one scalar model, make another scalar.constant.ts file.",
+      "The directory and filename convention is camelCase, such as `encourageInfo/encourageInfo.constant.ts`",
+      "The class name should be PascalCase, matching the camelCase directory name (e.g., EncourageInfo for encourageInfo)",
+      "Use `extends via((field) => ({...}))` pattern to define scalar classes, not decorators",
+      "Import `via` from `akanjs/constant` and `enumOf`, `ID`, `Int`, `Float`, `dayjs` from `akanjs/base`",
+      "The values of enum strings must be camelCase (e.g., 'waitPay', not 'WAIT_PAY')",
+      "Define enums using class pattern: `export class EnumName extends enumOf('enumName', [...] as const) {}`",
+      "The first argument of enumOf() is the enum name string used in dictionary/GraphQL",
+      "Use .optional() chain method for nullable fields, not { nullable: true } option",
+      "Use bracket notation for arrays ([Type]) rather than generics (Array<Type>)",
+      "Use factory functions for dynamic defaults: { default: () => dayjs() }, not { default: dayjs() }",
+      "Always export both the scalar class and enum classes",
+      "Add 'as const' to enum value arrays for better TypeScript type inference"
+    ]
+  },
+  "page": "/akanjs/(docs)/docs/scalar/constant/_index.tsx"
+}

package/cli/guidelines/scalarConstant/scalarConstant.instruction.md

@@ -0,0 +1,442 @@
+# Scalar Constant Implementation Guide for Akan.js
+
+## Purpose of Scalar Constants
+
+Scalar constants in Akan.js serve as the foundation for complex data modeling by:
+
+- Defining reusable value objects that can be embedded in other models
+- Representing complex data types without creating database collections
+- Providing standardized field definitions across the application
+- Enabling type-safe data modeling and validation
+- Serving as building blocks for larger domain models
+
+## File Structure and Location
+
+### Location Convention
+
+```
+{app,lib}/
+└── */lib/__scalar/
+    └── <scalarName>/                 # camelCase directory
+        └── <scalarName>.constant.ts  # scalar definition file
+```
+
+### Naming Standards
+
+- **Directory**: `camelCase` (e.g., `encourageInfo`, `geoLocation`)
+- **File**: `<scalarName>.constant.ts` (matches directory name)
+- **Scalar Class**: `PascalCase` (e.g., `EncourageInfo`, `GeoLocation`)
+- **Enum Class**: `PascalCase` (e.g., `Journey`, `NotiSetting`)
+- **Enum Values**: `camelCase` (e.g., `firstJoin`, `waitPay`)
+
+## Required Imports
+
+### Essential Framework Imports
+
+```typescript
+import { via } from "akanjs/constant";
+```
+
+### Common Base Types
+
+```typescript
+import { ID, Int, Float, dayjs, enumOf } from "akanjs/base";
+```
+
+### Cross-Scalar References
+
+```typescript
+import { OtherScalar } from "../otherScalar/otherScalar.constant";
+```
+
+## Basic Syntax with via()
+
+The `via()` function is the foundation for defining scalars. It takes a callback that receives the `field()` function, which you use to define each field's type and options.
+
+### Basic Structure
+
+```typescript
+import { via } from "akanjs/constant";
+
+export class ScalarName extends via((field) => ({
+  fieldName: field(FieldType),
+  fieldWithOptions: field(FieldType, { ...options }),
+})) {
+  // Optional: Add instance methods here
+}
+```
+
+### Simple Example
+
+```typescript
+import { via } from "akanjs/constant";
+
+export class RestrictInfo extends via((field) => ({
+  until: field(Date),
+  reason: field(String),
+})) {}
+```
+
+### Key Patterns
+
+| Pattern                    | Description                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `via((field) => ({...}))`  | Creates a class with typed fields. The callback receives the `field()` helper.   |
+| `field(Type)`              | Defines a single field. First argument is the type (String, Number, Date, etc.). |
+| `field(Type, { options })` | Optional second argument is an options object for defaults, validation, etc.     |
+
+## Available Field Types
+
+### Primitive Types
+
+```typescript
+import { ID, Int, Float } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class Example extends via((field) => ({
+  // String type
+  name: field(String),
+
+  // Number types
+  count: field(Int), // Integer
+  price: field(Float), // Floating point
+
+  // Boolean type
+  isActive: field(Boolean),
+
+  // Date type (internally uses Dayjs)
+  createdAt: field(Date),
+
+  // ID type (MongoDB ObjectId)
+  referenceId: field(ID),
+})) {}
+```
+
+### Array Types
+
+Array types are defined by wrapping the type in square brackets:
+
+```typescript
+export class Example extends via((field) => ({
+  // Array of strings
+  tags: field([String]),
+
+  // Array of numbers
+  scores: field([Int]),
+
+  // Array of other scalars
+  items: field([OtherScalar]),
+
+  // Nested arrays (2D matrix)
+  matrix: field([[Int]]),
+})) {}
+```
+
+### Optional Fields
+
+Optional fields can be defined using the `.optional()` chain:
+
+```typescript
+import { ID, Int } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class FileMeta extends via((field) => ({
+  fileId: field(ID).optional(), // Optional field
+  lastModifiedAt: field(Date),
+  size: field(Int),
+})) {}
+```
+
+## Field Options Reference
+
+| Option      | Type     | Default     | Description                                      | Example                       |
+| ----------- | -------- | ----------- | ------------------------------------------------ | ----------------------------- |
+| `default`   | Any/Func | `undefined` | Default field value (static or factory function) | `{ default: 0 }`              |
+| `min`       | Number   | -           | Minimum numeric value                            | `{ min: 0 }`                  |
+| `max`       | Number   | -           | Maximum numeric value                            | `{ max: 100 }`                |
+| `minlength` | Number   | -           | Minimum string length                            | `{ minlength: 3 }`            |
+| `maxlength` | Number   | -           | Maximum string length                            | `{ maxlength: 255 }`          |
+| `validate`  | Function | -           | Custom validation function                       | `{ validate: isPhoneNumber }` |
+| `example`   | Any      | -           | Example value for documentation                  | `{ example: [0, 0] }`         |
+
+### Field Options Examples
+
+```typescript
+import { dayjs, Int, Float } from "akanjs/base";
+import { isPhoneNumber } from "akanjs/common";
+import { via } from "akanjs/constant";
+
+export class OrderInfo extends via((field) => ({
+  // Static default value
+  quantity: field(Int, { default: 1 }),
+
+  // Dynamic default using factory function
+  orderedAt: field(Date, { default: () => dayjs() }),
+
+  // Number range validation
+  rating: field(Float, { min: 0, max: 5 }),
+
+  // String length validation
+  description: field(String, { minlength: 10, maxlength: 500 }),
+
+  // Custom validation function
+  phone: field(String, { validate: isPhoneNumber }),
+
+  // Combined options
+  price: field(Float, {
+    default: 0,
+    min: 0,
+    example: 29.99,
+  }),
+})) {}
+```
+
+### Static vs Dynamic Defaults
+
+- Use **static values** for constants: `{ default: 0 }`, `{ default: "active" }`
+- Use **factory functions** for values computed at creation time: `{ default: () => dayjs() }`, `{ default: () => new ObjectId() }`
+
+## Enum Definition with enumOf()
+
+The `enumOf()` function creates typed enum classes. Define enums before using them in your scalar fields.
+
+### Basic Enum
+
+```typescript
+import { enumOf } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+// Simple enum definition
+export class NotiSetting extends enumOf("notiSetting", ["disagree", "fewer", "normal", "block"]) {}
+
+// Using enum in a scalar
+export class NotiInfo extends via((field) => ({
+  setting: field(NotiSetting, { default: "normal" }),
+})) {}
+```
+
+### Enum with 'as const'
+
+For better TypeScript type inference, use `as const`:
+
+```typescript
+import { dayjs, enumOf } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+// Use "as const" for better type inference
+export class Status extends enumOf("status", ["pending", "active", "completed", "cancelled"] as const) {}
+
+export class Order extends via((field) => ({
+  status: field(Status, { default: "pending" }),
+  orderedAt: field(Date, { default: () => dayjs() }),
+})) {}
+```
+
+### Enum Key Points
+
+| Point                  | Description                                                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `enumOf(name, values)` | First argument is the enum name (used in dictionary/GraphQL). Second is the value array. |
+| camelCase Values       | Always use camelCase for enum values (e.g., `"waitPay"`, not `"WAIT_PAY"`).              |
+| `as const`             | Add `as const` to the values array for better TypeScript type inference.                 |
+
+## Instance Methods
+
+You can add instance methods directly to the scalar class for computed properties and utility functions:
+
+```typescript
+import { Int } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class Stock extends via((field) => ({
+  total: field(Int, { default: 0, min: 0 }),
+  current: field(Int, { default: 0, min: 0 }),
+})) {
+  getPercentage() {
+    if (this.total === 0) return 0;
+    return (this.current / this.total) * 100;
+  }
+}
+```
+
+### Method Guidelines
+
+- Instance methods have access to all fields via `this`
+- Use them for calculations based on field values
+- Methods defined in `constant.ts` are available on both server and client
+- For server-only logic, use `document.ts` instead
+
+## Static Methods
+
+Scalar classes can include static methods for common operations:
+
+```typescript
+import { enumOf, Float } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class CoordinateType extends enumOf("coordinateType", ["Point"] as const) {}
+
+export class Coordinate extends via((field) => ({
+  type: field(CoordinateType, { default: "Point" }),
+  coordinates: field([Float], { default: [0, 0], example: [127.114367, 37.497114] }),
+  altitude: field(Float, { default: 0 }),
+})) {
+  static getDistanceKm(loc1: Coordinate, loc2: Coordinate) {
+    const [lon1, lat1] = loc1.coordinates;
+    const [lon2, lat2] = loc2.coordinates;
+    const R = 6371; // Earth's radius in kilometers
+    // Distance calculation logic...
+    return distance;
+  }
+
+  static moveMeters(loc: Coordinate, x: number, y: number): Coordinate {
+    // Calculate new position...
+    return { ...loc, coordinates: [newLon, newLat] };
+  }
+}
+```
+
+## Common Mistakes and Fixes
+
+| Issue           | Wrong ❌                           | Correct ✅                                |
+| --------------- | ---------------------------------- | ----------------------------------------- |
+| Enum case       | `enumOf("status", ["ACTIVE"])`     | `enumOf("status", ["active"])`            |
+| Array syntax    | `field(Array<Int>)`                | `field([Int])`                            |
+| Dynamic default | `{ default: dayjs() }`             | `{ default: () => dayjs() }`              |
+| Missing export  | `class Status extends enumOf(...)` | `export class Status extends enumOf(...)` |
+| Optional field  | `field(ID, { nullable: true })`    | `field(ID).optional()`                    |
+
+### Important Note
+
+For Date defaults that should be computed at creation time, **always use a factory function**:
+
+```typescript
+// ❌ Wrong - creates a single fixed date at module load
+{ default: dayjs() }
+
+// ✅ Correct - creates a new date each time
+{ default: () => dayjs() }
+```
+
+## Implementation Checklist
+
+### File-Level
+
+- [ ] File location: `__scalar/<camelCase>/<camelCase>.constant.ts`
+- [ ] Import `via` from `akanjs/constant`
+- [ ] Import `enumOf` from `akanjs/base` (if using enums)
+- [ ] Export all classes (scalar and enums)
+
+### Naming
+
+- [ ] Use PascalCase for class names
+- [ ] Use camelCase for enum values
+- [ ] Class name matches directory name in PascalCase
+
+### Field Definition
+
+- [ ] Use `[Type]` syntax for arrays
+- [ ] Use factory functions for dynamic defaults
+- [ ] Use `.optional()` for nullable fields
+- [ ] Add `as const` for large enum value arrays
+
+## Full Examples
+
+### Basic Scalar Example
+
+```typescript
+// libs/payment/lib/__scalar/amount/amount.constant.ts
+import { Float } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class Amount extends via((field) => ({
+  value: field(Float, { min: 0, default: 0 }),
+  currency: field(String, { default: "USD" }),
+})) {}
+```
+
+### Scalar with Enum
+
+```typescript
+// apps/akasys/lib/__scalar/version/version.constant.ts
+import { dayjs, enumOf } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class VersionStatus extends enumOf("versionStatus", ["active", "expired"] as const) {}
+
+export class Version extends via((field) => ({
+  source: field(File).optional(),
+  appBuild: field(File).optional(),
+  build: field(File).optional(),
+  status: field(VersionStatus, { default: "active" }),
+  at: field(Date, { default: () => dayjs() }),
+})) {}
+```
+
+### Scalar with Optional Fields
+
+```typescript
+// apps/angelo/lib/__scalar/estimate/estimate.constant.ts
+import { Float, Int } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class Estimate extends via((field) => ({
+  name: field(String),
+  value: field(Float, { min: 0, default: 0 }),
+  num: field(Int, { min: 1, default: 1 }),
+  unit: field(String).optional(),
+  note: field(String).optional(),
+})) {}
+```
+
+### Complex Scalar with Static Methods
+
+```typescript
+// libs/util/lib/__scalar/coordinate/coordinate.constant.ts
+import { enumOf, Float } from "akanjs/base";
+import { via } from "akanjs/constant";
+
+export class CoordinateType extends enumOf("coordinateType", ["Point"] as const) {}
+
+export class Coordinate extends via((field) => ({
+  type: field(CoordinateType, { default: "Point" }),
+  coordinates: field([Float], { default: [0, 0], example: [127.114367, 37.497114] }),
+  altitude: field(Float, { default: 0 }),
+})) {
+  static getDistanceKm(loc1: Coordinate, loc2: Coordinate) {
+    const [lon1, lat1] = loc1.coordinates;
+    const [lon2, lat2] = loc2.coordinates;
+    const R = 6371;
+    // ... calculation logic
+    return distance;
+  }
+
+  static moveMeters(loc: Coordinate, x: number, y: number, z: number = 0): Coordinate {
+    const [lon, lat] = loc.coordinates;
+    const dx = ((x / 1000 / 6371) * (180 / Math.PI)) / Math.cos(lat * (Math.PI / 180));
+    const dy = (y / 1000 / 6371) * (180 / Math.PI);
+    return { ...loc, coordinates: [lon + dx, lat + dy], altitude: loc.altitude + z };
+  }
+}
+```
+
+## Pro Tips
+
+- **Keep scalars focused**: If it grows too large, split it into multiple scalars
+- **Value objects only**: Avoid adding ID or timestamp fields (use Models for that)
+- **Define enums first**: Define enums before the scalar class that uses them
+- **Dictionary support**: Don't forget to create `dictionary.ts` for i18n support
+- **Reusability**: Create separate scalars for commonly used structures
+
+## Summary
+
+1. **Location**: `__scalar/<camelCase>/<camelCase>.constant.ts`
+2. **Import**: `via` from `akanjs/constant`, `enumOf` from `akanjs/base`
+3. **Scalar Class**: `export class Name extends via((field) => ({...})) {}`
+4. **Enum Class**: `export class EnumName extends enumOf("enumName", [...] as const) {}`
+5. **Fields**: `field(Type)` or `field(Type, { options })`
+6. **Optional**: Use `.optional()` chain method
+7. **Arrays**: Use `[Type]` syntax
+8. **Enum Values**: Always camelCase
+
+Following these patterns ensures type-safe, maintainable scalar definitions that integrate seamlessly with the Akan.js framework's data modeling layer.

package/cli/guidelines/scalarDictionary/scalarDictionary.generate.json

@@ -0,0 +1,83 @@
+{
+  "title": "Scalar Dictionary",
+  "description": "How to create and maintain scalar.dictionary.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "scalarDictionary builder function implementation",
+      "path": "pkgs/akanjs/dictionary/scalarDictionary.ts"
+    },
+    {
+      "type": "source",
+      "description": "Translation types and interfaces",
+      "path": "pkgs/akanjs/dictionary/trans.ts"
+    },
+    {
+      "type": "source",
+      "description": "Dictionary exports and types",
+      "path": "pkgs/akanjs/dictionary/index.ts"
+    },
+    {
+      "type": "example",
+      "description": "Simple scalar dictionary examples",
+      "path": "{apps,libs}/**/lib/__scalar/*/*.dictionary.ts",
+      "query": "lines < 30",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Scalar dictionaries with enum translations",
+      "path": "{apps,libs}/**/lib/__scalar/*/*.dictionary.ts",
+      "query": "/\\.enum</",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Complete scalar dictionary with field and enum translations",
+      "path": "{apps,libs}/**/lib/__scalar/*/*.dictionary.ts",
+      "query": "lines > 30",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Scalar dictionaries with multiple enums",
+      "path": "{apps,libs}/**/lib/__scalar/*/*.dictionary.ts",
+      "query": "/\\.enum<.*\\.enum</",
+      "sample": 2
+    }
+  ],
+  "update": {
+    "filePath": "./scalarDictionary.instruction.md",
+    "contents": [
+      "Purpose of scalar dictionary files",
+      "File structure and naming conventions",
+      "Required imports from akanjs/dictionary",
+      "scalarDictionary() builder pattern",
+      "Builder methods: .of(), .model<T>(), .enum<T>()",
+      "Translation format with t() function and .desc() method",
+      "Type imports from constant file using import type",
+      "Enum name matching with enumOf() name",
+      "Type safety through generic parameters",
+      "Common mistakes and fixes",
+      "Best practices for translations",
+      "Implementation checklist",
+      "Full examples with multiple enums"
+    ],
+    "rules": [
+      "Import scalarDictionary from 'akanjs/dictionary'",
+      "Import types from constant file using 'import type' syntax",
+      "Initialize with language order array: scalarDictionary(['en', 'ko'])",
+      "Use .of() method to define scalar name and description",
+      "Use .model<Type>() method with generic to define field translations",
+      "Use .enum<Type>('enumName', ...) method to define enum translations",
+      "The enum name string in .enum() must exactly match the first argument of enumOf() in constant file",
+      "Always chain .desc() after t() to provide descriptions: t([...]).desc([...])",
+      "Use exactly two string elements in translation arrays: [English, Korean]",
+      "Export as 'dictionary': export const dictionary = scalarDictionary(...)...",
+      "Use type generics (.model<Type>, .enum<Type>) for TypeScript validation",
+      "Provide meaningful descriptions that explain purpose, not just repeat labels",
+      "Match language order consistently across all dictionaries in the project"
+    ]
+  },
+  "page": "/akanjs/(docs)/docs/scalar/dictionary/_index.tsx"
+}