iztro

https://iztro.com
Admin
iztro is a lightweight Ziwei Doushu chart calculation library with comprehensive documentation and...
Tokens:92,375
Snippets:791
Trust Score:6.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install IZTRO using npm

Source: https://iztro.com/quick-start.html

Install the iztro package using npm. This command adds iztro as a dependency to your project.

```bash
npm install iztro -S
```

--------------------------------

### Usage Example

Source: https://iztro.com/posts/astrolabe.html

Basic implementation of the bySolar function to generate an astrolabe.

```typescript
import { astro } from "iztro";

const astrolabe = astro.bySolar("2000-8-16", 2, "女", true, "zh-CN");
```

--------------------------------

### IZTRO package.json dependency

Source: https://iztro.com/quick-start.html

After successful installation, the 'iztro' package will be listed in your project's package.json dependencies.

```json
"dependencies": {
  "iztro": "^1.1.0"
}
```

--------------------------------

### Astrolabe Return Value Structure

Source: https://iztro.com/posts/astrolabe.html

Example of the JSON object returned by the bySolar function.

```javascript
{
  // 阳历日期
  solarDate: '2000-8-16',
  // 农历日期
  lunarDate: '二〇〇〇年七月十七',
  // 四柱
  chineseDate: '庚辰 甲申 丙午 庚寅',
  // 时辰
  time: '寅时',
  // 时辰对应的时间段
  timeRange: '03:00~05:00',
  // 星座
  sign: '狮子座',
  // 生肖
  zodiac: '龙',
  // 命宫地支
  earthlyBranchOfSoulPalace: '午',
  // 身宫地支
  earthlyBranchOfBodyPalace: '戌',
  // 命主
  soul: '破军',
  // 身主
  body: '文昌',
  // 五行局
  fiveElementsClass: '木三局',
  // 十二宫数据
  palaces: [
    {
      // 宫名
      name: '财帛',
      // 是否身宫
      isBodyPalace: false,
      // 是否来因宫
      isOriginalPalace: false,
      // 宫位天干
      heavenlyStem: '戊',
      // 宫位地支
      earthlyBranch: '寅',
      // 主星（含天马禄存）
      majorStars: [
        { name: '武曲', type: 'major', scope: 'origin', brightness: '得' },
        { name: '天相', type: 'major', scope: 'origin', brightness: '庙' },
        { name: '天马', type: 'tianma', scope: 'origin', brightness: '' },
      ],
      // 辅星（含六吉六煞）
      minorStars: [],
      // 杂耀
      adjectiveStars: [
        { name: '月解', type: 'helper', scope: 'origin' },
        { name: '三台', type: 'adjective', scope: 'origin' },
        { name: '天寿', type: 'adjective', scope: 'origin' },
        { name: '天巫', type: 'adjective', scope: 'origin' },
        { name: '天厨', type: 'adjective', scope: 'origin' },
        { name: '阴煞', type: 'adjective', scope: 'origin' },
        { name: '天哭', type: 'adjective', scope: 'origin' },
      ],
      // 长生12神
      changsheng12: '绝',
      // 博士12神
      boshi12: '蜚廉',
      // 流年将前12神
      jiangqian12: '岁驿',
      // 流年岁前12神
      suiqian12: '吊客',
      // 大限
      stage: { range: [44, 53], heavenlyStem: '戊' },
      // 小限
      ages: [9, 21, 33, 45, 57, 69, 81],
    },
    {
      name: '子女',
      isBodyPalace: false,
      isOriginalPalace: false,
      heavenlyStem: '己',
      earthlyBranch: '卯',
      majorStars: [
        { name: '太阳', type: 'major', scope: 'origin', brightness: '庙' },
        { name: '天梁', type: 'major', scope: 'origin', brightness: '庙' },
      ],
      minorStars: [],
      adjectiveStars: [{ name: '天刑', type: 'adjective', scope: 'origin' }],
      changsheng12: '墓',
      boshi12: '奏书',
      jiangqian12: '息神',
      suiqian12: '病符',
      stage: { range: [34, 43], heavenlyStem: '己' },
      ages: [8, 20, 32, 44, 56, 68, 80],
    },
    {
      name: '夫妻',
      isBodyPalace: false,
      isOriginalPalace: true,
      heavenlyStem: '庚',
      earthlyBranch: '辰',
      majorStars: [{ name: '七杀', type: 'major', scope: 'origin', brightness: '庙' }],
      minorStars: [
        { name: '右弼', type: 'soft', scope: 'origin', brightness: '' },
        { name: '火星', type: 'tough', scope: 'origin', brightness: '陷' },
      ],
      adjectiveStars: [
        { name: '封诰', type: 'adjective', scope: 'origin' },
        { name: '华盖', type: 'adjective', scope: 'origin' },
      ],
      changsheng12: '死',
      boshi12: '将军',
      jiangqian12: '华盖',
      suiqian12: '岁建',
      stage: { range: [24, 33], heavenlyStem: '庚' },
      ages: [7, 19, 31, 43, 55, 67, 79],
    },
    {
      name: '兄弟',
      isBodyPalace: false,
      isOriginalPalace: false,
      heavenlyStem: '辛',
      earthlyBranch: '巳',
      majorStars: [{ name: '天机', type: 'major', scope: 'origin', brightness: '平' }],
      minorStars: [],
      adjectiveStars: [
        { name: '天喜', type: 'flower', scope: 'origin' },
        { name: '天空', type: 'adjective', scope: 'origin' },
        { name: '孤辰', type: 'adjective', scope: 'origin' },
      ],
      changsheng12: '病',
      boshi12: '小耗',
      jiangqian12: '劫煞',
      suiqian12: '晦气',
      stage: { range: [14, 23], heavenlyStem: '辛' },
      ages: [6, 18, 30, 42, 54, 66, 78],
    },
    {
      name: '命宫',
      isBodyPalace: false,
      isOriginalPalace: false,
      heavenlyStem: '壬',
      earthlyBranch: '午',
      majorStars: [{ name: '紫微', type: 'major', scope: 'origin', brightness: '庙' }],
      minorStars: [{ name: '文曲', type: 'soft', scope: 'origin', brightness: '陷' }],
      adjectiveStars: [
        { name: '年解', type: 'helper', scope: 'origin' },
        { name: '凤阁', type: 'adjective', scope: 'origin' },
        { name: '天福', type: 'adjective', scope: 'origin' },

```

--------------------------------

### Use hasHoroscopeMutagen

Source: https://iztro.com/posts/horoscope.html

Example usage to determine if the yearly spouse palace contains a specific mutagen.

```typescript
import { astro } from "iztro";

const astrolabe = astro
  .astrolabeBySolarDate("2000-8-16", 2, "女", true, "zh-CN");
const flag = astrolabe
  .horoscope('2023-10-26', 2)
  .hasHoroscopeMutagen("夫妻", "yearly", "禄");
```

--------------------------------

### Get Star Instance

Source: https://iztro.com/posts/astrolabe.html

Retrieves the instance of a specific star by its name.

```typescript
type star = (starName: StarName) => IFunctionalStar;
```

```typescript
import { astro } from "iztro";

const astrolabe = astro.astrolabeBySolarDate("2000-8-16", 2, "女", true, "zh-CN");

// 获取 `紫微星` 所在宫位
const star = astrolabe.star("紫微");
```

--------------------------------

### Configuration for Brightness

Source: https://iztro.com/type-definition.html

Defines the global configuration for 'Brightness' (亮度) parameters.

```APIDOC
## ConfigBrightness

### Description
Defines the global configuration for 'Brightness' (亮度) parameters.

### Type Definition
```typescript
type ConfigBrightness = Partial<Record<StarName, Brightness[]>>;
```

### Properties
- This type is a partial record where keys are `StarName` and values are arrays of `Brightness`, representing the brightness levels associated with each star.
```

--------------------------------

### GET /astro/byLunar

Source: https://iztro.com/quick-start.html

Calculate the astrolabe information based on a lunar date.

```APIDOC
## GET /astro/byLunar

### Description
Retrieves the astrolabe information for a given lunar date.

### Method
GET

### Parameters
#### Query Parameters
- **lunarDateStr** (string) - Required - Lunar date in YYYY-M-D format
- **timeIndex** (number) - Required - Birth time index (0-12)
- **gender** (string) - Required - Gender (男/女)
- **isLeapMonth** (boolean) - Optional - Default: false. Whether it is a leap month
- **fixLeap** (boolean) - Optional - Default: true. Adjust leap month logic
- **language** (string) - Optional - Default: zh-CN. Language code

### Response
#### Success Response (200)
- **FunctionalAstrolabe** (object) - The generated astrolabe data
```

--------------------------------

### withOptions ^2.4.1

Source: https://iztro.com/posts/astrolabe.html

Retrieves astrolabe information using a flexible options object. This method acts as a wrapper for `bySolar` and `byLunar`.

```APIDOC
## withOptions ^2.4.1

### Description
Retrieves astrolabe information using a flexible options object. This method acts as a wrapper for `bySolar` and `byLunar`.

### Method
`withOptions`

### Parameters
#### Request Body
- **option** (Option) - Required - An object containing the details for retrieving astrolabe information.
  - **type** ('solar' | 'lunar') - Required - The type of date ('solar' or 'lunar').
  - **dateStr** (string) - Required - The birth date in 'YYYY-M-D' format.
  - **timeIndex** (number) - Required - The birth hour index (0-12).
  - **gender** (GenderName) - Required - The gender ('male'/'female').
  - **isLeapMonth** (boolean) - Optional - Defaults to `false`. Indicates if the month is a leap month.
  - **fixLeap** (boolean) - Optional - Defaults to `true`. Adjusts leap months.
  - **language** (Language) - Optional - Defaults to `zh-CN`. The language for the returned data.
  - **config** (Config) - Optional - Custom configuration for brightness, four transformations, and time split points.

### Request Example
```typescript
import { astro } from "iztro";

const astrolabe = astro.withOptions({
    type: 'solar',
    dateStr: '1999-12-29',
    timeIndex: 2,
    gender: 'female',
    isLeapMonth: false,
    fixLeap: true,
    language: 'zh-CN'
  });
```

### Response
#### Success Response
- **FunctionalAstrolabe** - The astrolabe information.

#### Response Example
(Refer to the example response for `bySolar`)
```

--------------------------------

### GET /astro/bySolar

Source: https://iztro.com/quick-start.html

Calculate the astrolabe information based on a solar date.

```APIDOC
## GET /astro/bySolar

### Description
Retrieves the astrolabe information for a given solar date.

### Method
GET

### Parameters
#### Query Parameters
- **solarDateStr** (string) - Required - Solar date in YYYY-M-D format
- **timeIndex** (number) - Required - Birth time index (0-12)
- **gender** (string) - Required - Gender (男/女)
- **fixLeap** (boolean) - Optional - Default: true. Adjust leap month logic
- **language** (string) - Optional - Default: zh-CN. Language code (zh-CN, zh-TW, en-US, ko-KR, ja-JP)

### Response
#### Success Response (200)
- **FunctionalAstrolabe** (object) - The generated astrolabe data
```

--------------------------------

### Importing the astro object

Source: https://iztro.com/posts/astrolabe.html

To use the static methods of the 'astro' object, you first need to import it into your code. This example shows how to import it using ES6 Modules or CommonJS.

```APIDOC
## Importing the astro object

### Description
To use the static methods of the `astro` object, please import it into your code first.

### ES6 Module
```ts
import { astro } from "iztro";
```

### CommonJS
```ts
const { astro } = require("iztro");
```
```

--------------------------------

### 加载插件

Source: https://iztro.com/posts/config-n-plugin.html

使用 loadPlugin 或 loadPlugins 方法将插件挂载到 astro 实例上。

```ts
import {astro} from iztro;

// 批量挂载插件
astro.loadPlugins([myTestPlugin， myTestPlugin2]);

// 逐个加载插件
astro.loadPlugin(myTestPlugin);
astro.loadPlugin(myTestPlugin2);
```

--------------------------------

### Retrieve a Palace

Source: https://iztro.com/posts/astrolabe.html

Use the palace method to get a specific palace object by its index or name.

```typescript
type palace = (
  indexOrName: number | PalaceName
) => IFunctionalPalace | undefined;
```

```typescript
import { astro } from "iztro";

const astrolabe = astro.astrolabeBySolarDate("2000-8-16", 2, "女", true, "zh-CN");

// 获取 `寅宫`
const palace = astrolabe.palace(0);

// 获取 `命宫`
const soulPalace = astrolabe.palace("命宫");
```

--------------------------------

### Retrieve Astrolabe with Options

Source: https://iztro.com/posts/astrolabe.html

A wrapper method that simplifies calling bySolar or byLunar by accepting a single configuration object.

```typescript
type Option = {
  type: 'solar' | 'lunar';
  dateStr: string;
  timeIndex: number;
  gender: GenderName;
  isLeapMonth?: boolean;
  fixLeap?: boolean;
  language?: Language;
  config?: Config;
};

export type withOptions = (
  option: Option
) => FunctionalAstrolabe;
```

```typescript
import { astro } from "iztro";

const astrolabe = astro.withOptions({
    type: 'solar',
    dateStr: '1999-12-29',
    timeIndex: 2,
    gender: 'female',
    isLeapMonth: false,
    fixLeap: true,
    language: 'zh-CN'
  })
```

--------------------------------

### GET /star/getHoroscopeStar

Source: https://iztro.com/quick-start.html

Retrieve specific horoscope stars based on heavenly stem and earthly branch.

```APIDOC
## GET /star/getHoroscopeStar

### Description
Retrieves horoscope stars for a specific scope (decadal or yearly).

### Method
GET

### Parameters
#### Query Parameters
- **heavenlyStem** (string) - Required - Heavenly stem name
- **earthlyBranch** (string) - Required - Earthly branch name
- **scope** (string) - Required - 'decadal' or 'yearly'

### Response
#### Success Response (200)
- **Star[][]** (array) - Array of star objects
```

--------------------------------

### Palace State Methods

Source: https://iztro.com/posts/palace.html

Methods for checking the status of a specific palace, including occupancy and flying star interactions.

```APIDOC
## isEmpty()

### Description
Determines if a palace is empty (contains no major stars). An optional parameter allows excluding specific stars from this check.

### Parameters
- **excludeStars** (StarName[]) - Optional - Array of star names to exclude from the empty check.

### Response
- **boolean** - Returns true if the palace is empty.

## fliesTo()

### Description
Checks if the source palace has flying stars (四化) directed to the target palace. Returns true if all specified mutagens are present.

### Parameters
- **to** (number | PalaceName) - Required - Target palace index or name.
- **withMutagens** (Mutagen | Mutagen[]) - Required - The flying stars (禄, 权, 科, 忌) to check.

### Response
- **boolean** - Returns true if all specified mutagens fly to the target.

## selfMutaged()

### Description
Checks if the current palace has self-mutations (自化). All provided mutagens must be present for a true result.

### Parameters
- **withMutagens** (Mutagen | Mutagen[]) - Required - The flying stars to check.

### Response
- **boolean** - Returns true if the palace has the specified self-mutations.
```

--------------------------------

### 获取小限宫位

Source: https://iztro.com/posts/horoscope.html

调用 `agePalace()` 方法获取 `小限` 所在宫位。此方法不接受参数。

```typescript
import { astro } from "iztro";

const astrolabe = astro
  .astrolabeBySolarDate("2000-8-16", 2, "女", true, "zh-CN");
const agePalace = astrolabe
  .horoscope('2023-10-26', 2)
  .agePalace();
```

--------------------------------

### 配置全局参数

Source: https://iztro.com/posts/config-n-plugin.html

在调用排盘方法前使用 astro.config() 设置自定义的四化或星曜亮度。

```ts
import { astro } from 'iztro';

astro.config({
  mutagens: { 庚: ['太阳', '武曲', '天同', '天相'] },
  brightness: {
    贪狼: ['旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺'],
  },
});
```

--------------------------------

### Get Horoscope Data

Source: https://iztro.com/posts/astrolabe.html

Retrieves horoscope data. If no parameters are provided, it uses the current system time.

```typescript
type horoscope = (date?: string | Date, timeIndex?: number) => FunctionalHoroscope;
```

```typescript
import { astro } from "iztro";

const astrolabe = astro.astrolabeBySolarDate("2000-8-16", 2, "女", true, "zh-CN");
const horoscope = astrolabe.horoscope();
```

--------------------------------

### Get Chinese Zodiac by Lunar Year

Source: https://iztro.com/posts/astrolabe.html

Retrieves the Chinese zodiac animal for a given lunar year.

```typescript
type getZodiacByLunarYear = (year: number, language?: Language) => string;
```

```typescript
import { astro } from 'isztro';

const result = getZodiacByLunarYear(2023);
```

```typescript
兔
```

--------------------------------

### Config Object

Source: https://iztro.com/type-definition.html

Defines the global parameters object for project configuration.

```APIDOC
## Config Object

### Description
Defines the global parameters object.

### Type Definition
```typescript
type Config = {
  // Star-related mutation configuration
  mutagens?: ConfigMutagens;
  // Star brightness configuration
  brightness?: ConfigBrightness;
  // Year division point configuration
  yearDivide?: 'normal' | 'exact';
  // Horoscope division point configuration (^v2.4.3)
  horoscopeDivide?: 'normal' | 'exact';
  // Minor division point configuration, 'normal' divides by natural year, 'birthday' divides by birthday (^v2.4.5)
  // Defaults to 'normal'
  ageDivide?: 'normal' | 'birthday';
};
```

### Notes on Division Points
- When `yearDivide` and `horoscopeDivide` are set to `normal`, the division is based on the first day of the lunar new year.
- When set to `exact`, the division is based on the beginning of spring (立春).
```

--------------------------------

### Get Chinese Zodiac by Solar Date

Source: https://iztro.com/posts/astrolabe.html

Retrieves the Chinese zodiac animal for a given solar date.

```typescript
type getZodiacBySolarDate = (solarDateStr: string, language?: Language) => string;
```

```typescript
import { astro } from 'isztro';

const result = getZodiacBySolarDate('2023-2-20');
```

```typescript
兔
```
Tokens:
Raw