├── .yarnrc.yml ├── types ├── Body.ts ├── Params.ts ├── DeepPartial.ts ├── HttpMethod.ts ├── JsonCompatible.ts ├── ResponseMessage.ts ├── StrawError.ts ├── BaseDocument.ts ├── ServerMessage.ts ├── ListFilter.ts ├── FetchOptions.ts ├── index.ts └── DocumentMeta.ts ├── .prettierignore ├── consts └── index.ts ├── resource ├── index.ts ├── component.tsx └── useResource.ts ├── utils ├── index.ts ├── pagination-converter.ts ├── pagination-converter.test.ts ├── human-timediff.test.ts └── human-timediff.ts ├── .prettierrc.js ├── auth ├── index.ts ├── useCurrentUser.ts ├── useLogout.ts └── useLogin.ts ├── vitest.config.ts ├── cache ├── index.ts ├── useCacheClear.ts ├── useCache.ts ├── useCacheUpdate.ts ├── useCacheInvalidate.ts ├── getCacheKey.ts └── getCacheKey.test.ts ├── api ├── message.ts ├── strip.ts ├── error.ts └── index.ts ├── eslint.config.mjs ├── document ├── useStatus.ts ├── useTimeAgo.ts ├── useDelete.ts ├── useMethod.ts ├── useAction.ts └── index.ts ├── index.ts ├── .github └── workflows │ ├── release.yml │ ├── publish.yml │ ├── tests.yml │ └── documentation.yml ├── document-list ├── useCount.ts └── index.ts ├── document-meta └── index.ts ├── package.json ├── list ├── filters.ts ├── filters.test.ts └── index.ts ├── readme.md ├── context └── index.tsx ├── axios └── index.ts ├── architecture.md ├── .gitignore ├── assets └── bytsolv-logo.svg ├── tsconfig.json └── LICENSE /.yarnrc.yml: -------------------------------------------------------------------------------- 1 | nodeLinker: node-modules 2 | -------------------------------------------------------------------------------- /types/Body.ts: -------------------------------------------------------------------------------- 1 | export type Body = Record; 2 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # Ignore artifacts: 2 | build 3 | coverage 4 | -------------------------------------------------------------------------------- /types/Params.ts: -------------------------------------------------------------------------------- 1 | export type Params = Record; 2 | -------------------------------------------------------------------------------- /consts/index.ts: -------------------------------------------------------------------------------- 1 | export const defaultCacheTTL = 300000; // 5 minutes 2 | -------------------------------------------------------------------------------- /types/DeepPartial.ts: -------------------------------------------------------------------------------- 1 | export type DeepPartial = T extends object 2 | ? { [P in keyof T]?: DeepPartial } 3 | : T; 4 | -------------------------------------------------------------------------------- /resource/index.ts: -------------------------------------------------------------------------------- 1 | export { StrawResource } from './component'; 2 | export { useResource, type Resource } from './useResource'; 3 | -------------------------------------------------------------------------------- /utils/index.ts: -------------------------------------------------------------------------------- 1 | export { humanTimediff } from './human-timediff'; 2 | export { paginationConverter } from './pagination-converter'; 3 | -------------------------------------------------------------------------------- /types/HttpMethod.ts: -------------------------------------------------------------------------------- 1 | export type HttpMethod = 2 | | 'get' 3 | | 'post' 4 | | 'put' 5 | | 'delete' 6 | | 'patch' 7 | | 'options'; 8 | -------------------------------------------------------------------------------- /.prettierrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | printWidth: 80, 3 | singleQuote: true, 4 | plugins: ['prettier-plugin-organize-imports'], 5 | }; 6 | -------------------------------------------------------------------------------- /auth/index.ts: -------------------------------------------------------------------------------- 1 | export { useCurrentUser } from './useCurrentUser'; 2 | export { useLogin } from './useLogin'; 3 | export { useLogout } from './useLogout'; 4 | -------------------------------------------------------------------------------- /types/JsonCompatible.ts: -------------------------------------------------------------------------------- 1 | export type JsonCompatible = 2 | | string 3 | | number 4 | | boolean 5 | | null 6 | | JsonCompatible[] 7 | | { [key: string]: JsonCompatible }; 8 | -------------------------------------------------------------------------------- /types/ResponseMessage.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * Response message type. This is the most common response type. 3 | */ 4 | export type ResponseMessage = { 5 | message: T; 6 | }; 7 | -------------------------------------------------------------------------------- /vitest.config.ts: -------------------------------------------------------------------------------- 1 | import { defineConfig } from 'vitest/config'; 2 | 3 | export default defineConfig({ 4 | test: { 5 | coverage: { 6 | reporter: ['text', 'json', 'json-summary'], 7 | }, 8 | }, 9 | }); 10 | -------------------------------------------------------------------------------- /types/StrawError.ts: -------------------------------------------------------------------------------- 1 | export type StrawError = { 2 | status: number; 3 | message: string; 4 | title?: string; 5 | indicator?: 'blue' | 'green' | 'orange' | 'red' | 'yellow'; 6 | raise_exception?: boolean; 7 | __frappe_exc_id?: string; 8 | }; 9 | -------------------------------------------------------------------------------- /cache/index.ts: -------------------------------------------------------------------------------- 1 | export { getCacheKey } from './getCacheKey'; 2 | export { useCache } from './useCache'; 3 | export { useCacheClear } from './useCacheClear'; 4 | export { useCacheInvalidate } from './useCacheInvalidate'; 5 | export { useCacheUpdate } from './useCacheUpdate'; 6 | -------------------------------------------------------------------------------- /types/BaseDocument.ts: -------------------------------------------------------------------------------- 1 | export interface BaseDocument { 2 | name: string; 3 | creation: string; 4 | modified: string; 5 | owner: string; 6 | modified_by: string; 7 | docstatus: 0 | 1 | 2; 8 | parent?: string; 9 | parentfield?: string; 10 | parenttype?: string; 11 | idx?: number; 12 | } 13 | -------------------------------------------------------------------------------- /types/ServerMessage.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * Frappe's server messages. Used to display alerts and errors. 3 | */ 4 | export type ServerMessage = { 5 | message: string; 6 | title?: string; 7 | indicator?: 'blue' | 'green' | 'orange' | 'red' | 'yellow'; 8 | raise_exception?: 0 | 1; 9 | __frappe_exc_id?: string; 10 | }; 11 | -------------------------------------------------------------------------------- /api/message.ts: -------------------------------------------------------------------------------- 1 | import { type AxiosResponse } from 'axios'; 2 | import type { ServerMessage } from '../types'; 3 | 4 | export const toServerMessages = (response: AxiosResponse): ServerMessage[] => { 5 | const _server_messages = (response.data as any)._server_messages || '[]'; 6 | return JSON.parse(_server_messages).map(JSON.parse); 7 | }; 8 | -------------------------------------------------------------------------------- /eslint.config.mjs: -------------------------------------------------------------------------------- 1 | import pluginJs from '@eslint/js'; 2 | import globals from 'globals'; 3 | import tseslint from 'typescript-eslint'; 4 | 5 | export default [ 6 | { files: ['**/*.{js,mjs,cjs,ts}'] }, 7 | { languageOptions: { globals: globals.browser } }, 8 | pluginJs.configs.recommended, 9 | ...tseslint.configs.recommended, 10 | ]; 11 | -------------------------------------------------------------------------------- /cache/useCacheClear.ts: -------------------------------------------------------------------------------- 1 | import { useContext } from 'react'; 2 | import { StrawContext } from '../context'; 3 | 4 | /** 5 | * Clear whole cache storage. This will delete all entries from cache. 6 | */ 7 | export const useCacheClear = () => { 8 | const { cache } = useContext(StrawContext); 9 | 10 | return () => { 11 | cache.clear(); 12 | }; 13 | }; 14 | -------------------------------------------------------------------------------- /document/useStatus.ts: -------------------------------------------------------------------------------- 1 | import { BaseDocument } from '../types'; 2 | 3 | export const useStatus = (doc?: T) => { 4 | switch (doc?.docstatus) { 5 | case 0: 6 | return 'Draft'; 7 | case 1: 8 | return 'Submitted'; 9 | case 2: 10 | return 'Cancelled'; 11 | default: 12 | return 'Unknown'; 13 | } 14 | }; 15 | -------------------------------------------------------------------------------- /types/ListFilter.ts: -------------------------------------------------------------------------------- 1 | export type ListFilterOperator = 2 | | '=' 3 | | '>' 4 | | '<' 5 | | '>=' 6 | | '<=' 7 | | '<>' 8 | | 'like' 9 | | '!=' 10 | | 'Timespan'; 11 | 12 | export type ListFilterValueExtended = { 13 | operator: ListFilterOperator; 14 | value: T[K]; 15 | }; 16 | 17 | export type ListFilter = { 18 | [key in keyof T]?: T[key] | ListFilterValueExtended; 19 | }; 20 | -------------------------------------------------------------------------------- /auth/useCurrentUser.ts: -------------------------------------------------------------------------------- 1 | import { useResource } from '../resource'; 2 | import type { ResponseMessage } from '../types'; 3 | 4 | const apiMethod = 'frappe.auth.get_logged_user'; 5 | 6 | /** 7 | * Get logged in user. 8 | * @returns Logged in user's id 9 | */ 10 | export const useCurrentUser = ({ fetchOnMount = true } = {}) => { 11 | return useResource(apiMethod, { 12 | transform: (data) => data.message, 13 | fetchOnMount, 14 | }); 15 | }; 16 | -------------------------------------------------------------------------------- /utils/pagination-converter.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * Convert page `index` and `size` to `start` and `limit`. 3 | * @param pageIndex - Index of page, starting from 0. 4 | * @param pageSize - Page size. 5 | * @returns `start` and `limit`. 6 | */ 7 | export const paginationConverter = ({ 8 | pageIndex, 9 | pageSize, 10 | }: { 11 | pageIndex: number; 12 | pageSize: number; 13 | }) => { 14 | const start = pageIndex * pageSize; 15 | const limit = pageSize; 16 | 17 | return [start, limit]; 18 | }; 19 | -------------------------------------------------------------------------------- /resource/component.tsx: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import { Resource, useResource } from '.'; 3 | import type { JsonCompatible } from '../types'; 4 | 5 | export const StrawResource = ({ 6 | url, 7 | options, 8 | children, 9 | }: { 10 | url: Parameters>[0]; 11 | options?: Parameters>[1] & { fetchOnMount?: boolean }; 12 | children: (resource: Resource) => React.ReactNode; 13 | }) => { 14 | return children(useResource(url, options)); 15 | }; 16 | -------------------------------------------------------------------------------- /api/strip.ts: -------------------------------------------------------------------------------- 1 | const strippables = ['_server_messages'] as const; 2 | 3 | export const strip = (data: T) => { 4 | const stripped = data; 5 | 6 | // If the data is not an object, return it as is. 7 | if (typeof stripped !== 'object' || stripped === null) { 8 | return stripped; 9 | } 10 | 11 | // Remove strippable keys from the object. 12 | for (const strippable of strippables) { 13 | if (strippable in stripped) { 14 | delete stripped[strippable]; 15 | } 16 | } 17 | 18 | return stripped; 19 | }; 20 | -------------------------------------------------------------------------------- /index.ts: -------------------------------------------------------------------------------- 1 | export { useApi } from './api'; 2 | export { useCurrentUser, useLogin, useLogout } from './auth'; 3 | export { 4 | useCache, 5 | useCacheClear, 6 | useCacheInvalidate, 7 | useCacheUpdate, 8 | } from './cache'; 9 | export { Straw } from './context'; 10 | export { useDocument } from './document'; 11 | export { useDocumentList } from './document-list'; 12 | export { useDocumentMeta } from './document-meta'; 13 | export { useList } from './list'; 14 | export { StrawResource, useResource } from './resource'; 15 | export * from './types'; 16 | -------------------------------------------------------------------------------- /document/useTimeAgo.ts: -------------------------------------------------------------------------------- 1 | import { formatDistanceToNow, parseISO } from 'date-fns'; 2 | import { BaseDocument } from '../types'; 3 | 4 | export const useTimeAgo = (doc?: T) => { 5 | if (!doc) { 6 | return { 7 | createdAt: '', 8 | modifiedAt: '', 9 | }; 10 | } 11 | 12 | const format = (dateStr: string) => { 13 | return formatDistanceToNow(parseISO(dateStr), { 14 | addSuffix: true, 15 | }); 16 | }; 17 | 18 | return { 19 | createdAt: format(doc.creation), 20 | modifiedAt: format(doc.modified), 21 | }; 22 | }; 23 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Create Release 2 | 3 | on: 4 | push: 5 | tags: 6 | - 'v*' 7 | 8 | jobs: 9 | release: 10 | name: Create Release 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Checkout 14 | uses: actions/checkout@v4 15 | - name: Create changelog text 16 | uses: loopwerk/tag-changelog@v1 17 | with: 18 | token: ${{ secrets.GITHUB_TOKEN }} 19 | exclude_types: other,doc,chore,ci 20 | - name: Release 21 | uses: softprops/action-gh-release@v2 22 | with: 23 | token: ${{ secrets.TOKEN }} 24 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish Package to npmjs 2 | 3 | on: 4 | release: 5 | types: [published] 6 | 7 | jobs: 8 | publish: 9 | name: Publish Package to NPM 10 | runs-on: ubuntu-latest 11 | permissions: 12 | contents: read 13 | id-token: write 14 | steps: 15 | - uses: actions/checkout@v4 16 | - uses: actions/setup-node@v4 17 | with: 18 | node-version: '23.x' 19 | registry-url: 'https://registry.npmjs.org' 20 | - run: npm install 21 | - run: npm publish --provenance --access public 22 | env: 23 | NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} 24 | -------------------------------------------------------------------------------- /types/FetchOptions.ts: -------------------------------------------------------------------------------- 1 | import type { Body } from './Body'; 2 | import type { HttpMethod } from './HttpMethod'; 3 | import type { JsonCompatible } from './JsonCompatible'; 4 | import type { Params } from './Params'; 5 | import type { ServerMessage } from './ServerMessage'; 6 | import type { StrawError } from './StrawError'; 7 | 8 | export type FetchOptions = { 9 | method?: HttpMethod; 10 | body?: Body; 11 | params?: Params; 12 | cache?: JsonCompatible; 13 | cacheTime?: string | number; 14 | onSuccess?: (data: T) => void; 15 | onError?: (error: StrawError) => void; 16 | onMessages?: (messages: ServerMessage[]) => void; 17 | }; 18 | -------------------------------------------------------------------------------- /utils/pagination-converter.test.ts: -------------------------------------------------------------------------------- 1 | import { expect, test } from 'vitest'; 2 | import { paginationConverter } from './pagination-converter'; 3 | 4 | test('Pagination Converter page 0', () => { 5 | const pagination = { 6 | pageIndex: 0, 7 | pageSize: 10, 8 | }; 9 | const [start, limit] = paginationConverter(pagination); 10 | expect(start).toBe(0); 11 | expect(limit).toBe(10); 12 | }); 13 | 14 | test('Pagination Converter page 2', () => { 15 | const pagination = { 16 | pageIndex: 2, 17 | pageSize: 10, 18 | }; 19 | const [start, limit] = paginationConverter(pagination); 20 | expect(start).toBe(20); 21 | expect(limit).toBe(10); 22 | }); 23 | -------------------------------------------------------------------------------- /auth/useLogout.ts: -------------------------------------------------------------------------------- 1 | import { useResource } from '../resource'; 2 | import type { FetchOptions, ResponseMessage } from '../types'; 3 | 4 | type R = ResponseMessage & { 5 | home_page: string; 6 | full_name: string; 7 | }; 8 | 9 | const method = 'post'; 10 | const apiMethod = 'logout'; 11 | 12 | /** 13 | * Logout from Frappe server. 14 | * @returns Promise 15 | */ 16 | export const useLogout = ({ onSuccess, onError }: FetchOptions = {}) => { 17 | const resource = useResource(apiMethod, { 18 | method, 19 | fetchOnMount: false, 20 | onSuccess, 21 | onError, 22 | }); 23 | 24 | return { 25 | ...resource, 26 | logout: resource.refresh, 27 | }; 28 | }; 29 | -------------------------------------------------------------------------------- /cache/useCache.ts: -------------------------------------------------------------------------------- 1 | import { useContext } from 'react'; 2 | import { StrawContext } from '../context'; 3 | import { type JsonCompatible } from '../types'; 4 | import { getCacheKey } from './getCacheKey'; 5 | 6 | /** 7 | * Get cached value against `key`. 8 | * @param key - Key against which cached data should be returned. 9 | * @returns Cached data. 10 | */ 11 | export const useCache = () => { 12 | const { cache } = useContext(StrawContext); 13 | 14 | return (key: JsonCompatible) => { 15 | // Get actual cache key. 16 | const cacheKey = getCacheKey(key); 17 | 18 | // If cache has the key, return cached data. 19 | if (cache.has(cacheKey)) { 20 | return cache.get(cacheKey); 21 | } 22 | }; 23 | }; 24 | -------------------------------------------------------------------------------- /types/index.ts: -------------------------------------------------------------------------------- 1 | export type { BaseDocument } from './BaseDocument'; 2 | export type { Body } from './Body'; 3 | export type { DeepPartial } from './DeepPartial.ts'; 4 | export type { 5 | DocumentMeta, 6 | DocumentMetaField, 7 | DocumentMetaPermission, 8 | } from './DocumentMeta'; 9 | export type { FetchOptions } from './FetchOptions'; 10 | export type { HttpMethod } from './HttpMethod'; 11 | export type { JsonCompatible } from './JsonCompatible'; 12 | export type { 13 | ListFilter, 14 | ListFilterOperator, 15 | ListFilterValueExtended, 16 | } from './ListFilter'; 17 | export type { Params } from './Params'; 18 | export type { ResponseMessage } from './ResponseMessage'; 19 | export type { ServerMessage } from './ServerMessage'; 20 | export type { StrawError } from './StrawError'; 21 | -------------------------------------------------------------------------------- /cache/useCacheUpdate.ts: -------------------------------------------------------------------------------- 1 | import { useContext } from 'react'; 2 | import { StrawContext } from '../context'; 3 | import { type JsonCompatible } from '../types'; 4 | import { humanTimediff } from '../utils'; 5 | import { getCacheKey } from './getCacheKey'; 6 | 7 | /** 8 | * Update cache of `key`. 9 | * @param key - Key against which cache should be updated. 10 | * @param value - Value to update. 11 | * @param timeout - Time to live for the cache. 12 | */ 13 | export const useCacheUpdate = () => { 14 | const { cache } = useContext(StrawContext); 15 | 16 | return ( 17 | key: JsonCompatible, 18 | value: T, 19 | { timeout = 0 }: { timeout?: string | number } = {}, 20 | ) => { 21 | const cacheKey = getCacheKey(key); 22 | const ttl = humanTimediff(timeout); 23 | cache.set(cacheKey, value, { 24 | ttl, 25 | }); 26 | return value; 27 | }; 28 | }; 29 | -------------------------------------------------------------------------------- /utils/human-timediff.test.ts: -------------------------------------------------------------------------------- 1 | import { expect, test } from 'vitest'; 2 | import { humanTimediff } from './human-timediff'; 3 | 4 | test('humanTimediff: 1h', () => { 5 | expect(humanTimediff('1h')).toBe(3600000); 6 | }); 7 | 8 | test('humanTimediff: 1m', () => { 9 | expect(humanTimediff('1m')).toBe(60000); 10 | }); 11 | 12 | test('humanTimediff: 1s', () => { 13 | expect(humanTimediff('1s')).toBe(1000); 14 | }); 15 | 16 | test('humanTimediff: 1ms', () => { 17 | expect(humanTimediff('1ms')).toBe(1); 18 | }); 19 | 20 | test('humanTimediff: 1us', () => { 21 | expect(humanTimediff('1us')).toBe(0.001); 22 | }); 23 | 24 | test('humanTimediff: 1ns', () => { 25 | expect(humanTimediff('1ns')).toBe(0.000001); 26 | }); 27 | 28 | test('humanTimediff: 1h1m1s1ms1us1ns', () => { 29 | expect(humanTimediff('1h1m1s1ms1us1ns')).toBe(3661001.001001); 30 | }); 31 | 32 | test('humanTimediff: Invalid input', () => { 33 | expect(() => humanTimediff('invalid input')).toThrow(); 34 | }); 35 | -------------------------------------------------------------------------------- /document/useDelete.ts: -------------------------------------------------------------------------------- 1 | import { useResource } from '../resource'; 2 | import type { FetchOptions } from '../types'; 3 | 4 | /** 5 | * Hook for deleting a document resource. 6 | * @param doctype - Document type. 7 | * @param docname - Document name. 8 | * @param options - Options for the hook. 9 | * @returns `DeleteResource` 10 | */ 11 | export const useDelete = ( 12 | doctype: string, 13 | docname: string, 14 | { onSuccess, onError }: FetchOptions = {}, 15 | ) => { 16 | const resource = useResource('frappe.client.delete', { 17 | method: 'post', 18 | fetchOnMount: false, 19 | onSuccess, 20 | onError, 21 | }); 22 | 23 | const deleteDoc = async () => { 24 | try { 25 | await resource.refresh({ 26 | body: { 27 | doctype, 28 | name: docname, 29 | }, 30 | }); 31 | } catch (error) { 32 | console.error(error); 33 | } 34 | }; 35 | 36 | return { 37 | ...resource, 38 | deleteDoc, 39 | }; 40 | }; 41 | -------------------------------------------------------------------------------- /document-list/useCount.ts: -------------------------------------------------------------------------------- 1 | import { tranformFilter } from '../list/filters'; 2 | import { useResource } from '../resource'; 3 | import type { FetchOptions, ListFilter, ResponseMessage } from '../types'; 4 | 5 | const apiMethod = 'frappe.desk.reportview.get_count'; 6 | 7 | export const useCount = ( 8 | doctype: string, 9 | filters?: ListFilter, 10 | orFilters?: ListFilter, 11 | { 12 | cache, 13 | cacheTime, 14 | onSuccess, 15 | onError, 16 | fetchOnMount = true, 17 | }: FetchOptions & { fetchOnMount?: boolean } = {}, 18 | ) => { 19 | return useResource, number>(apiMethod, { 20 | params: { 21 | doctype, 22 | filters: filters && JSON.stringify(tranformFilter(filters)), 23 | or_filters: orFilters && JSON.stringify(tranformFilter(orFilters)), 24 | }, 25 | cache, 26 | cacheTime, 27 | transform: (data) => data.message, 28 | onSuccess, 29 | onError, 30 | fetchOnMount, 31 | }); 32 | }; 33 | -------------------------------------------------------------------------------- /auth/useLogin.ts: -------------------------------------------------------------------------------- 1 | import { useResource } from '../resource'; 2 | import type { FetchOptions, ResponseMessage } from '../types'; 3 | 4 | interface R extends ResponseMessage { 5 | home_page: string; 6 | full_name: string; 7 | } 8 | 9 | const method = 'post'; 10 | const apiMethod = 'login'; 11 | 12 | /** 13 | * Login to Frappe server, using provided credentials. 14 | * @param username - Username to login with. 15 | * @param password - Password to login with. 16 | * @returns `Resource` object. 17 | */ 18 | export const useLogin = ({ onSuccess, onError }: FetchOptions = {}) => { 19 | const resource = useResource(apiMethod, { 20 | method, 21 | fetchOnMount: false, 22 | onSuccess, 23 | onError, 24 | }); 25 | 26 | const login = (username: string, password: string) => { 27 | return resource.refresh({ 28 | body: { 29 | usr: username, 30 | pwd: password, 31 | }, 32 | }); 33 | }; 34 | 35 | return { 36 | ...resource, 37 | login, 38 | }; 39 | }; 40 | -------------------------------------------------------------------------------- /cache/useCacheInvalidate.ts: -------------------------------------------------------------------------------- 1 | import { useContext } from 'react'; 2 | import { StrawContext } from '../context'; 3 | import { type JsonCompatible } from '../types'; 4 | import { getCacheKey } from './getCacheKey'; 5 | 6 | type CacheInvalidateOptions = { 7 | onSuccess?: () => void; 8 | onError?: () => void; 9 | }; 10 | 11 | /** 12 | * Invalidate cache of a specific key. 13 | * @param key - Key against which cache should be cleared. 14 | */ 15 | export const useCacheInvalidate = () => { 16 | const { cache } = useContext(StrawContext); 17 | 18 | return ( 19 | key: JsonCompatible, 20 | { onSuccess = () => {}, onError = () => {} }: CacheInvalidateOptions = {}, 21 | ) => { 22 | // Get actual cache key. 23 | const cacheKey = getCacheKey(key); 24 | 25 | // Delete cache entry. 26 | const status = cache.delete(cacheKey); 27 | 28 | // Run success or error callbacks. 29 | if (status) onSuccess(); 30 | else onError(); 31 | 32 | // Return status of cache deletion. 33 | return status; 34 | }; 35 | }; 36 | -------------------------------------------------------------------------------- /document-meta/index.ts: -------------------------------------------------------------------------------- 1 | import { useResource } from '../resource'; 2 | import { BaseDocument, DocumentMeta, FetchOptions } from '../types'; 3 | 4 | type Doc = BaseDocument & DocumentMeta; 5 | type Meta = Record; 6 | type Response = { 7 | docs: Doc[]; 8 | }; 9 | 10 | interface UseDocumentMetaOptions extends FetchOptions { 11 | fetchOnMount?: boolean; 12 | } 13 | 14 | /** 15 | * Hook for fetching document meta. 16 | * @param doctype - Document type. 17 | * @param options - Fetch options. 18 | * @returns `Meta` - Meta information for the document and child documents. 19 | */ 20 | export function useDocumentMeta( 21 | doctype: string, 22 | options?: UseDocumentMetaOptions, 23 | ) { 24 | return useResource('frappe.desk.form.load.getdoctype', { 25 | params: { 26 | doctype, 27 | }, 28 | transform: (data) => { 29 | return data.docs.reduce((acc, doc) => { 30 | acc[doc.name] = doc; 31 | return acc; 32 | }, {} as Meta); 33 | }, 34 | ...options, 35 | }); 36 | } 37 | -------------------------------------------------------------------------------- /utils/human-timediff.ts: -------------------------------------------------------------------------------- 1 | const whole = /^((\d+(\.\d+)*)(ns|ms|us|µs|m|s|h))+$/; 2 | const pieces = /((\d+(\.\d+)*)(ns|ms|us|µs|m|s|h))/g; 3 | const measure = /(ns|ms|us|µs|m|s|h)/g; 4 | 5 | const multipliers: Record = { 6 | ns: 1e-6, 7 | us: 0.001, 8 | µs: 0.001, 9 | ms: 1, 10 | s: 1000, 11 | m: 60000, 12 | h: 3.6e6, 13 | }; 14 | 15 | const analyse = (time: string) => { 16 | const unit = time.match(measure)?.shift() || ''; 17 | time = time.substring(0, time.length - unit.length); 18 | 19 | return parseFloat(time) * multipliers[unit]; 20 | }; 21 | 22 | export const humanTimediff = (time: string | number) => { 23 | // If the time is already a number, return it. 24 | if (typeof time === 'number') { 25 | return time; 26 | } 27 | 28 | // If the time is a string, check if it is valid. 29 | if (!whole.test(time)) { 30 | throw new Error('invalid time'); 31 | } 32 | 33 | // Get the actual time from the string. 34 | return time.match(pieces)?.reduce((acc, value) => { 35 | return acc + analyse(value); 36 | }, 0); 37 | }; 38 | -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: Run Tests 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | pull_request: 8 | branches: 9 | - main 10 | 11 | jobs: 12 | test: 13 | name: Run Tests 14 | permissions: 15 | contents: read 16 | pull-requests: write 17 | runs-on: ubuntu-latest 18 | strategy: 19 | matrix: 20 | node-version: 21 | - 18.x 22 | - 20.x 23 | - 23.x 24 | steps: 25 | - name: Checkout code 26 | uses: actions/checkout@v4 27 | - name: Use Node.js ${{ matrix.node-version }} 28 | uses: actions/setup-node@v4 29 | with: 30 | node-version: ${{ matrix.node-version }} 31 | - name: Enable Corepack 32 | run: corepack enable 33 | - name: Use yarn v4 34 | run: yarn set version berry 35 | - name: Install dependencies 36 | run: yarn 37 | - name: Run tests 38 | run: yarn test --coverage.enabled true 39 | - name: Report Coverage 40 | uses: davelosert/vitest-coverage-report-action@v2 41 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "frappe-straw", 3 | "version": "0.15.0", 4 | "description": "Yet another straw to consume Frappe", 5 | "main": "index.ts", 6 | "repository": "git@github.com:ssiyad/frappe-straw.git", 7 | "author": "Sabu Siyad ", 8 | "license": "GPL-3.0", 9 | "scripts": { 10 | "test": "vitest" 11 | }, 12 | "dependencies": { 13 | "@isaacs/ttlcache": "^1.4.1", 14 | "axios": "^1.8.4", 15 | "date-fns": "^4.1.0", 16 | "qs": "^6.14.0", 17 | "react": "^18.0.0" 18 | }, 19 | "devDependencies": { 20 | "@eslint/js": "^9.25.1", 21 | "@types/qs": "^6.9.18", 22 | "@types/react": "^19.1.2", 23 | "@vitest/coverage-v8": "^3.1.2", 24 | "eslint": "^9.25.1", 25 | "globals": "^15.10.0", 26 | "prettier": "3.5.3", 27 | "prettier-plugin-organize-imports": "^4.1.0", 28 | "typescript": "^5.8.3", 29 | "typescript-eslint": "^8.31.0", 30 | "vitest": "^3.1.2" 31 | }, 32 | "packageManager": "yarn@4.8.1+sha512.bc946f2a022d7a1a38adfc15b36a66a3807a67629789496c3714dd1703d2e6c6b1c69ff9ec3b43141ac7a1dd853b7685638eb0074300386a59c18df351ef8ff6" 33 | } 34 | -------------------------------------------------------------------------------- /document-list/index.ts: -------------------------------------------------------------------------------- 1 | import { useMemo } from 'react'; 2 | import { useList, type UseListOptions } from '../list'; 3 | import { type FetchOptions } from '../types'; 4 | import { useCount } from './useCount'; 5 | 6 | interface UseDocumentListOptions extends Omit, 'url'> { 7 | doctype: string; 8 | } 9 | 10 | interface DocumentList extends ReturnType> { 11 | useCount: (options?: FetchOptions) => ReturnType; 12 | } 13 | 14 | /** 15 | * Hook to manage a document (of doctype) list resource with pagination. 16 | */ 17 | export function useDocumentList({ 18 | doctype, 19 | ...listOptions 20 | }: UseDocumentListOptions): DocumentList { 21 | // Construct the URL for the resource. 22 | const url = useMemo(() => `/api/resource/${doctype}`, [doctype]); 23 | 24 | // Use the list resource hook. 25 | const listResource = useList({ 26 | url, 27 | ...listOptions, 28 | }); 29 | 30 | return { 31 | ...listResource, 32 | useCount: (options) => 33 | useCount(doctype, listOptions.filters, listOptions.orFilters, options), 34 | }; 35 | } 36 | -------------------------------------------------------------------------------- /types/DocumentMeta.ts: -------------------------------------------------------------------------------- 1 | export interface DocumentMetaField { 2 | fieldname: string; 3 | label: string; 4 | fieldtype: string; 5 | options?: string; 6 | reqd?: number; 7 | default?: any; 8 | hidden?: number; 9 | read_only?: number; 10 | in_list_view?: number; 11 | in_standard_filter?: number; 12 | [key: string]: any; 13 | } 14 | 15 | export interface DocumentMetaPermission { 16 | permlevel: number; 17 | read: number; 18 | write: number; 19 | create: number; 20 | delete: number; 21 | submit: number; 22 | cancel: number; 23 | amend: number; 24 | report: number; 25 | export: number; 26 | print: number; 27 | email: number; 28 | share: number; 29 | [key: string]: any; 30 | } 31 | 32 | export interface DocumentMeta { 33 | name: string; 34 | fields: DocumentMetaField[]; 35 | permissions: DocumentMetaPermission[]; 36 | is_submittable?: number; 37 | is_tree?: number; 38 | allow_import?: number; 39 | quick_entry?: number; 40 | title_field?: string; 41 | image_field?: string; 42 | sort_field?: string; 43 | sort_order?: string; 44 | hide_toolbar?: number; 45 | [key: string]: any; 46 | } 47 | -------------------------------------------------------------------------------- /list/filters.ts: -------------------------------------------------------------------------------- 1 | import type { 2 | ListFilter, 3 | ListFilterOperator, 4 | ListFilterValueExtended, 5 | } from '../types'; 6 | 7 | /** 8 | * @template T - Generic type 9 | * @param input - Filter object 10 | * @returns Transformed filter object compatible with Frappe 11 | */ 12 | export const tranformFilter = (input: ListFilter) => { 13 | type V = ListFilter[keyof T]; 14 | type I = [keyof T, ListFilterOperator, V]; 15 | 16 | return Object.keys(input) 17 | .map((k) => { 18 | const key = k as keyof T; 19 | const val = input[key]; 20 | const operator = 21 | val && typeof val === 'object' 22 | ? (val as ListFilterValueExtended).operator 23 | : '='; 24 | const value = 25 | val && typeof val === 'object' 26 | ? (val as ListFilterValueExtended).value 27 | : val; 28 | 29 | return { 30 | key, 31 | operator, 32 | value, 33 | }; 34 | }) 35 | .filter((x) => !!x.value) 36 | .reduce( 37 | (acc, x) => { 38 | // @ts-ignore 39 | acc.push([x.key, x.operator, x.value].map(encodeURIComponent)); 40 | return acc; 41 | }, 42 | [] as unknown as I[], 43 | ); 44 | }; 45 | -------------------------------------------------------------------------------- /api/error.ts: -------------------------------------------------------------------------------- 1 | import { AxiosError } from 'axios'; 2 | import type { ServerMessage, StrawError } from '../types'; 3 | 4 | export const toStrawError = ({ 5 | message, 6 | response, 7 | status = 500, 8 | }: AxiosError): StrawError => { 9 | // Frappe server messages are stored in the _server_messages key. 10 | // Check `ServerMessage` type for more details. 11 | const serverMessagesStr = (response?.data as any)._server_messages || '[]'; 12 | 13 | // Parse server messages string to JSON. 14 | const err: ServerMessage = JSON.parse( 15 | JSON.parse(serverMessagesStr).at(0) ?? null, 16 | ); 17 | 18 | // If the error is a server message, return it. 19 | if (err) { 20 | return { 21 | ...err, 22 | raise_exception: !!err.raise_exception, 23 | status, 24 | }; 25 | } 26 | 27 | // If the error is a validation error, return it. 28 | // @ts-ignore `message` may exist on the response object. 29 | if (status > 400 && response?.data?.message) { 30 | return { 31 | // @ts-ignore `message` may exist on the response object. 32 | message: response.data.message, 33 | status, 34 | }; 35 | } 36 | 37 | // If the error is a network error, return it. 38 | return { 39 | message, 40 | status, 41 | }; 42 | }; 43 | -------------------------------------------------------------------------------- /cache/getCacheKey.ts: -------------------------------------------------------------------------------- 1 | import type { JsonCompatible, Params } from '../types'; 2 | 3 | /** 4 | * Constructs a cache key based on the provided parameters. 5 | * @param cache - The cache configuration, which can be a boolean, string, or object. 6 | * @param url - The URL of the API request. 7 | * @param method - The HTTP method of the API request. 8 | * @param params - The query parameters of the API request. 9 | * @param body - The body of the API request. 10 | * @returns The constructed cache key, or false if caching is not enabled. 11 | */ 12 | export const getCacheKey = ( 13 | cache?: JsonCompatible, 14 | url?: string, 15 | method?: string, 16 | params?: Params, 17 | body?: Record, 18 | ) => { 19 | // If `cache` is not defined, we don't have to cache anything. 20 | if (!cache) { 21 | return false; 22 | } 23 | 24 | // If `cache` is `true`, it probably means the user wants to cache the entire 25 | // api call. 26 | if (cache && typeof cache === 'boolean') { 27 | return JSON.stringify({ url, method, body, params }); 28 | } 29 | 30 | // If `cache` is a string, it is probably a cache key. 31 | if (typeof cache === 'string') { 32 | return cache; 33 | } 34 | 35 | // If `cache` is an object, the user is more deliberate about what to cache. 36 | return JSON.stringify(cache); 37 | }; 38 | -------------------------------------------------------------------------------- /.github/workflows/documentation.yml: -------------------------------------------------------------------------------- 1 | name: Deploy Documentation 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | deploy: 10 | name: Deploy Documentation 11 | permissions: 12 | contents: read 13 | pages: write 14 | id-token: write 15 | environment: 16 | name: github-pages 17 | url: ${{ steps.deployment.outputs.page_url }} 18 | runs-on: ubuntu-latest 19 | steps: 20 | - name: Checkout code 21 | uses: actions/checkout@v4 22 | - name: Setup Node 23 | uses: actions/setup-node@v4 24 | with: 25 | node-version: 23.x 26 | cache: npm 27 | - name: Enable Corepack 28 | run: corepack enable 29 | - name: Use yarn v4 30 | run: yarn set version berry 31 | - name: Install dependencies 32 | run: yarn install 33 | - name: TSDoc Action 34 | uses: erikyo/tsdoc-action@v1 35 | with: 36 | source_dir: ./* 37 | output_dir: ./docs 38 | front_page: readme.md 39 | - name: Setup Pages 40 | uses: actions/configure-pages@v5 41 | - name: Upload artifact 42 | uses: actions/upload-pages-artifact@v3 43 | with: 44 | path: ./docs 45 | - name: Deploy to GitHub Pages 46 | id: deployment 47 | uses: actions/deploy-pages@v4 48 | -------------------------------------------------------------------------------- /cache/getCacheKey.test.ts: -------------------------------------------------------------------------------- 1 | import { expect, test } from 'vitest'; 2 | import { getCacheKey } from './getCacheKey'; 3 | 4 | test('Cache: `true` as key', () => { 5 | expect( 6 | getCacheKey(true, '/an/internal/url', 'get', undefined, undefined), 7 | ).toBe('{"url":"/an/internal/url","method":"get"}'); 8 | }); 9 | 10 | test('Cache: `false` as key', () => { 11 | expect( 12 | getCacheKey(false, '/an/internal/url', 'get', undefined, undefined), 13 | ).toBe(false); 14 | }); 15 | 16 | test('Cache: Array of strings', () => { 17 | expect(getCacheKey(['a', 'b', 'c'])).toBe('["a","b","c"]'); 18 | }); 19 | 20 | test('Cache: Array of numbers', () => { 21 | expect(getCacheKey([1, 2, 3])).toBe('[1,2,3]'); 22 | }); 23 | 24 | test('Cache: Array of objects', () => { 25 | expect(getCacheKey([{ a: 1 }, { b: 2 }, { c: 3 }])).toBe( 26 | '[{"a":1},{"b":2},{"c":3}]', 27 | ); 28 | }); 29 | 30 | test('Cache: Array of mixed', () => { 31 | expect(getCacheKey([1, 'a', { b: 2 }])).toBe('[1,"a",{"b":2}]'); 32 | }); 33 | 34 | test('Cache: Object', () => { 35 | expect(getCacheKey({ a: 1, b: 2, c: 3 })).toBe('{"a":1,"b":2,"c":3}'); 36 | }); 37 | 38 | test('Cache: Nested Object', () => { 39 | expect(getCacheKey({ a: { b: { c: 3 } } })).toBe('{"a":{"b":{"c":3}}}'); 40 | }); 41 | 42 | test('Cache: Nested Array', () => { 43 | expect(getCacheKey([1, [2, [3]]])).toBe('[1,[2,[3]]]'); 44 | }); 45 | 46 | test('Cache: Nested Mixed', () => { 47 | expect(getCacheKey([1, { a: [2, 3] }])).toBe('[1,{"a":[2,3]}]'); 48 | }); 49 | -------------------------------------------------------------------------------- /document/useMethod.ts: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import { useResource } from '../resource'; 3 | import type { 4 | BaseDocument, 5 | FetchOptions, 6 | Params, 7 | ResponseMessage, 8 | } from '../types'; 9 | 10 | type R = ResponseMessage & { 11 | docs: U[]; 12 | }; 13 | 14 | const apiMethod = 'run_doc_method'; 15 | 16 | /** 17 | * Run a method on a document. 18 | * @param method - Method name. 19 | * @param doctype - Document type. 20 | * @param docname - Document name. 21 | */ 22 | export const useMethod = ( 23 | method: string, 24 | doctype: string, 25 | docname: string, 26 | setParentData: React.Dispatch>, 27 | { onSuccess, onError }: FetchOptions = {}, 28 | ) => { 29 | const resource = useResource, U>(apiMethod, { 30 | method: 'post', 31 | fetchOnMount: false, 32 | transform: (data) => data.docs[0], 33 | onSuccess, 34 | onError, 35 | }); 36 | 37 | const run = async (params?: Params) => { 38 | try { 39 | const parentDoc = await resource.refresh({ 40 | params: { 41 | method, 42 | dt: doctype, 43 | dn: docname, 44 | args: JSON.stringify(params), 45 | }, 46 | }); 47 | 48 | if (parentDoc) { 49 | setParentData(parentDoc); 50 | } 51 | 52 | return parentDoc; 53 | } catch (error) { 54 | console.error(error); 55 | } 56 | }; 57 | 58 | return { 59 | ...resource, 60 | run, 61 | }; 62 | }; 63 | -------------------------------------------------------------------------------- /document/useAction.ts: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import { useResource } from '../resource'; 3 | import type { BaseDocument, DeepPartial, FetchOptions } from '../types'; 4 | 5 | type R = { 6 | docs: T[]; 7 | }; 8 | 9 | const actionMethod = 'frappe.desk.form.save.savedocs'; 10 | 11 | /** 12 | * Run an action on a document. 13 | * @param action - Action name. 14 | * @param doc - Document data. 15 | * @param setParentData - Set parent data. 16 | * @returns `useResource` object. 17 | */ 18 | export const useAction = ( 19 | action: 'Save' | 'Submit' | 'Cancel', 20 | doctype: string, 21 | doc?: T, 22 | setParentData?: React.Dispatch>, 23 | { onSuccess, onError }: FetchOptions = {}, 24 | ) => { 25 | const resource = useResource, T>(actionMethod, { 26 | method: 'post', 27 | fetchOnMount: false, 28 | transform: (data) => data.docs[0], 29 | onSuccess, 30 | onError, 31 | }); 32 | 33 | const run = async (values?: DeepPartial) => { 34 | try { 35 | const parentDoc = await resource.refresh({ 36 | body: { 37 | doc: JSON.stringify({ 38 | doctype, 39 | ...doc, 40 | ...values, 41 | }), 42 | action, 43 | }, 44 | }); 45 | 46 | if (parentDoc && setParentData) { 47 | setParentData(parentDoc); 48 | } 49 | 50 | return parentDoc; 51 | } catch (error) { 52 | console.error(error); 53 | } 54 | }; 55 | 56 | return { 57 | ...resource, 58 | run, 59 | }; 60 | }; 61 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 |
2 |

Frappe Straw

3 | 4 |
5 | 6 | 7 | 8 |
9 | 10 | Minimal, pleasant and easy to use 11 | Frappe 12 | client. 13 | 14 |
Made with ❤️ at Bytsolv.
15 |
16 | 17 | ## Demo 18 | You can install the demo app from 19 | [here](https://github.com/ssiyad/frappe-straw-demo). It contain example code 20 | and a playground. This can also be used as a test suite for development of this 21 | plugin. 22 | 23 | ## Installation 24 | ```shell 25 | npm install frappe-straw 26 | ``` 27 | 28 | Example 29 | ```typescript 30 | import { useDocument } from 'frappe-straw'; 31 | import { type BaseDocument } from 'frappe-straw/types'; 32 | 33 | const { data, error, loading, refresh } = useDocument( 34 | 'Role', 35 | 'Guest', 36 | { 37 | fetchOnMount: false, 38 | }, 39 | ); 40 | ``` 41 | 42 | ## Inspirations 43 | - [Frappe JS SDK](https://github.com/The-Commit-Company/frappe-js-sdk) 44 | - [frappe-ui](https://ui.frappe.io/) 45 | 46 | ## Self Promotion 47 | Like this project? Give it a star! ⭐, and spread the word! 🚀. And if you are 48 | feeling especially charitable, follow [Sabu Siyad](https://ssiyad.com) on 49 | [GitHub](https://github.com/ssiyad) 50 | -------------------------------------------------------------------------------- /context/index.tsx: -------------------------------------------------------------------------------- 1 | import TTLCache from '@isaacs/ttlcache'; 2 | import { AxiosInstance } from 'axios'; 3 | import { createContext, PropsWithChildren, useMemo } from 'react'; 4 | import { createAxios } from '../axios'; 5 | import { defaultCacheTTL } from '../consts'; 6 | import type { ServerMessage, StrawError } from '../types'; 7 | 8 | const defaultCache = new TTLCache({ 9 | max: 1000, 10 | ttl: defaultCacheTTL, 11 | }); 12 | 13 | export const StrawContext = createContext<{ 14 | client: AxiosInstance; 15 | cache: TTLCache; 16 | onError?: (error: StrawError) => void; 17 | onMessages?: (messages: ServerMessage[]) => void; 18 | }>({ 19 | client: {} as AxiosInstance, 20 | cache: defaultCache, 21 | }); 22 | 23 | /** 24 | * Straw provider. Provides an Axios client and cache to the rest of the app. 25 | * Must be used before any other Straw hooks. 26 | * @param url - Base URL for the API. 27 | * @param token - Function to get an auth token. 28 | * @param tokenType - Type of token to use. 29 | * @param children - Child components. 30 | * @returns Straw Provider 31 | */ 32 | export const Straw = ({ 33 | url, 34 | token, 35 | tokenType, 36 | onError, 37 | onMessages, 38 | children, 39 | }: PropsWithChildren<{ 40 | url?: string; 41 | token?: () => string; 42 | tokenType?: 'Bearer' | 'token'; 43 | onError?: (error: StrawError) => void; 44 | onMessages?: (messages: ServerMessage[]) => void; 45 | }>) => { 46 | const client = useMemo( 47 | () => createAxios({ url, token, tokenType }), 48 | [url, token, tokenType], 49 | ); 50 | 51 | const cache = useMemo( 52 | () => new TTLCache({ max: 1000, ttl: 1000 * 60 * 5 }), 53 | [], 54 | ); 55 | 56 | return ( 57 | 58 | {children} 59 | 60 | ); 61 | }; 62 | -------------------------------------------------------------------------------- /list/filters.test.ts: -------------------------------------------------------------------------------- 1 | import { expect, test } from 'vitest'; 2 | import { tranformFilter } from './filters'; 3 | 4 | test('Key Value Pair', () => { 5 | expect( 6 | tranformFilter({ 7 | foo: 'bar', 8 | bar: 42, 9 | baz: true, 10 | }), 11 | ).toEqual([ 12 | ['foo', '=', 'bar'], 13 | ['bar', '=', 42], 14 | ['baz', '=', true], 15 | ]); 16 | }); 17 | 18 | test('Key Value Pair with Operator', () => { 19 | expect( 20 | tranformFilter({ 21 | foo: { operator: '>', value: 42 }, 22 | bar: { operator: '<', value: 42 }, 23 | baz: { operator: '!=', value: 42 }, 24 | }), 25 | ).toEqual([ 26 | ['foo', '>', 42], 27 | ['bar', '<', 42], 28 | ['baz', '!=', 42], 29 | ]); 30 | }); 31 | 32 | test('Key Value Pair with Operator and Value', () => { 33 | expect( 34 | tranformFilter({ 35 | foo: { operator: 'like', value: 'bar' }, 36 | bar: { operator: 'Timespan', value: 42 }, 37 | }), 38 | ).toEqual([ 39 | ['foo', 'like', 'bar'], 40 | ['bar', 'Timespan', 42], 41 | ]); 42 | }); 43 | 44 | test('Empty Object', () => { 45 | expect(tranformFilter({})).toEqual([]); 46 | }); 47 | 48 | test('Empty Value', () => { 49 | expect(tranformFilter({ foo: undefined })).toEqual([]); 50 | }); 51 | 52 | test('Empty Value and Operator', () => { 53 | expect(tranformFilter({ foo: {} })).toEqual([]); 54 | }); 55 | 56 | test('Empty Value and Operator with Key', () => { 57 | expect(tranformFilter({ foo: { operator: '>', value: undefined } })).toEqual( 58 | [], 59 | ); 60 | }); 61 | 62 | test('Mixed key values', () => { 63 | expect( 64 | tranformFilter({ 65 | foo: 'bar', 66 | bar: { operator: '>', value: 42 }, 67 | baz: { operator: 'like', value: 'bar' }, 68 | }), 69 | ).toEqual([ 70 | ['foo', '=', 'bar'], 71 | ['bar', '>', 42], 72 | ['baz', 'like', 'bar'], 73 | ]); 74 | }); 75 | -------------------------------------------------------------------------------- /list/index.ts: -------------------------------------------------------------------------------- 1 | import { useMemo } from 'react'; 2 | import { useResource } from '../resource'; 3 | import type { FetchOptions, ListFilter } from '../types'; 4 | import { tranformFilter } from './filters'; 5 | 6 | interface R { 7 | data: T[]; 8 | } 9 | 10 | export interface UseListOptions extends FetchOptions { 11 | url: string; 12 | fields?: (keyof T)[] | '*'; 13 | filters?: ListFilter; 14 | orFilters?: ListFilter; 15 | group?: keyof T; 16 | sort?: { 17 | field: keyof T; 18 | direction: 'asc' | 'desc'; 19 | }; 20 | start?: number; 21 | limit?: number; 22 | fetchOnMount?: boolean; 23 | } 24 | 25 | interface List extends ReturnType, T[]>> { 26 | currentPage: number; 27 | } 28 | 29 | /** 30 | * Hook to manage a list resource with pagination. 31 | */ 32 | export function useList({ 33 | url, 34 | fields, 35 | filters, 36 | orFilters, 37 | group, 38 | sort, 39 | start = 0, 40 | limit = 10, 41 | onSuccess, 42 | onError, 43 | onMessages, 44 | cache, 45 | cacheTime, 46 | fetchOnMount, 47 | }: UseListOptions): List { 48 | const params = useMemo( 49 | () => ({ 50 | fields: fields === '*' ? [fields] : fields, 51 | filters: filters && JSON.stringify(tranformFilter(filters)), 52 | or_filters: orFilters && JSON.stringify(tranformFilter(orFilters)), 53 | group_by: group, 54 | order_by: sort && `${sort.field.toString()} ${sort.direction}`, 55 | limit, 56 | limit_start: start, 57 | as_dict: true, 58 | }), 59 | [ 60 | JSON.stringify({ 61 | fields, 62 | filters, 63 | orFilters, 64 | group, 65 | sort, 66 | start, 67 | limit, 68 | }), 69 | ], 70 | ); 71 | 72 | const resource = useResource, T[]>(url, { 73 | params, 74 | cache, 75 | cacheTime, 76 | transform: (data) => data.data, 77 | onSuccess, 78 | onError, 79 | onMessages, 80 | fetchOnMount, 81 | }); 82 | 83 | const currentPage = Math.floor(start / limit) + 1; 84 | 85 | return { 86 | ...resource, 87 | currentPage, 88 | }; 89 | } 90 | -------------------------------------------------------------------------------- /api/index.ts: -------------------------------------------------------------------------------- 1 | import { useCallback, useContext } from 'react'; 2 | import { getCacheKey, useCache, useCacheUpdate } from '../cache'; 3 | import { defaultCacheTTL } from '../consts'; 4 | import { StrawContext } from '../context'; 5 | import type { FetchOptions, JsonCompatible } from '../types'; 6 | import { toStrawError } from './error'; 7 | import { toServerMessages } from './message'; 8 | import { strip } from './strip'; 9 | 10 | /** 11 | * API request parameters. 12 | */ 13 | interface ApiRequest extends FetchOptions { 14 | url: string; 15 | cache?: JsonCompatible; 16 | } 17 | 18 | /** 19 | * Hook to make an API request with caching. 20 | */ 21 | export const useApi = () => { 22 | const { 23 | client, 24 | cache: cacheStore, 25 | onError: onErrorGlobal, 26 | onMessages: onMessagesGlobal, 27 | } = useContext(StrawContext); 28 | const cacheGet = useCache(); 29 | const cacheUpdate = useCacheUpdate(); 30 | 31 | return useCallback( 32 | async ({ 33 | url, 34 | method = 'get', 35 | params, 36 | body, 37 | cache, 38 | cacheTime = defaultCacheTTL, 39 | onError = onErrorGlobal, 40 | onMessages = onMessagesGlobal, 41 | }: ApiRequest): Promise => { 42 | const cacheKey = getCacheKey(cache, url, method, params, body); 43 | const cacheData = cacheGet(cacheKey); 44 | if (cacheData) return cacheData; 45 | 46 | try { 47 | const response = await client.request({ 48 | baseURL: url.startsWith('http') ? '' : undefined, 49 | url, 50 | method, 51 | params, 52 | data: body, 53 | }); 54 | 55 | if (cacheKey) { 56 | cacheUpdate(cacheKey, response.data, { 57 | timeout: cacheTime, 58 | }); 59 | } 60 | 61 | const messages = toServerMessages(response); 62 | if (messages.length > 0) onMessages?.(messages); 63 | const stripped = strip(response.data); 64 | return stripped; 65 | } catch (error: any) { 66 | const err = toStrawError(error); 67 | onError?.(err); 68 | throw err; 69 | } 70 | }, 71 | [client, cacheStore], 72 | ); 73 | }; 74 | -------------------------------------------------------------------------------- /axios/index.ts: -------------------------------------------------------------------------------- 1 | import axios, { AxiosInstance, RawAxiosRequestHeaders } from 'axios'; 2 | import qs from 'qs'; 3 | 4 | declare global { 5 | interface Window { 6 | csrf_token: string; 7 | } 8 | } 9 | 10 | const HEADER_SITE_NAME = 'X-Frappe-Site-Name'; 11 | const HEADER_CSRF_TOKEN = 'X-Frappe-CSRF-Token'; 12 | 13 | type Args = { 14 | url?: string; 15 | token?: () => string; 16 | tokenType?: 'Bearer' | 'token'; 17 | }; 18 | 19 | /** 20 | * Create an axios client with necessary headers. 21 | * 22 | * @param args - Arguments to create axios client. 23 | * @returns AxiosInstance 24 | */ 25 | export const createAxios = (args: Args): AxiosInstance => { 26 | // Create axios instance. 27 | const a = axios.create({ 28 | baseURL: args.url, 29 | headers: headers(args), 30 | withCredentials: true, 31 | paramsSerializer: (params) => { 32 | return qs.stringify( 33 | Object.fromEntries( 34 | Object.entries(params).map(([key, value]) => [ 35 | key, 36 | Array.isArray(value) ? JSON.stringify(value) : value, 37 | ]), 38 | ), 39 | { encode: false }, 40 | ); 41 | }, 42 | }); 43 | 44 | return a; 45 | }; 46 | 47 | /** 48 | * Create headers for axios request. 49 | * 50 | * @param args - Arguments to create headers. 51 | * @returns RawAxiosRequestHeaders 52 | */ 53 | const headers = (args: Args): RawAxiosRequestHeaders => { 54 | // Init default headers. 55 | const headers: RawAxiosRequestHeaders = { 56 | Accept: 'application/json', 57 | 'Content-Type': 'application/json; charset=utf-8', 58 | }; 59 | 60 | // Set token if provided. 61 | if (args.tokenType && args.token) { 62 | headers.Authorization = [args.tokenType, args.token()].join(' '); 63 | } 64 | 65 | // In case of server environments, return headers. 66 | if (typeof window == 'undefined' || typeof document == 'undefined') { 67 | return headers; 68 | } 69 | 70 | // Set site name if available. 71 | if (window.location) { 72 | if (args.url !== window.location.origin) { 73 | } else { 74 | headers[HEADER_SITE_NAME] = window.location.hostname; 75 | } 76 | } 77 | 78 | // Set CSRF token if available. 79 | if (window.csrf_token && window.csrf_token !== '{{ csrf_token }}') { 80 | headers[HEADER_CSRF_TOKEN] = window.csrf_token; 81 | } 82 | 83 | return headers; 84 | }; 85 | -------------------------------------------------------------------------------- /architecture.md: -------------------------------------------------------------------------------- 1 | ## `init` 2 | This package exposes a method called `init`, which will accept parameters such 3 | as URL, global `onError` and `onSuccess` handlers, and extra headers. This 4 | method will create an API client and will store it in either `window` or 5 | `global` (node) from where it can be accessed by other methods. This eliminates 6 | the need to pass the client from one method to another manually. `init` is 7 | mandatory for the working of this package. 8 | 9 | ## `api` 10 | A raw, unmodified `api` method has to be exposed for customisability. This 11 | method can be used to call frappe or any other endpoint like any other api 12 | client. This method is the base of all other methods and resources. For example, 13 | the `resource`, which we will cover later, is an extension of `api`. The 14 | response of `api` will be modified, additional methods will be added and 15 | parameters will be different. But under the hood, it will be using `api`. So if 16 | anyone wanted to use any endpoint (or external URLs), they can use `api`. 17 | 18 | ## `auth` 19 | Set of auth related methods. It can be used to login, logout and get current 20 | user. This module must be able to handle authorisation in the future. 21 | 22 | ## `resource` 23 | Resource is the fundamental data structure of this package. Any `resource` will 24 | contain helper methods to load, reset and refresh the data. Resources can be 25 | cached using unique identifiers. The scope of resource can be vague. A basic 26 | use case to fetch some data that is neither a doc or a list. 27 | 28 | ## `docResource` 29 | Document resources are `resource`s that fetch a document. A document can have 30 | actions such as save, delete, submit and cancel in addition to load, reset and 31 | refresh. An additional array of white listed method can be used on a document 32 | resource. This feature however is on hold until a solution to support proper 33 | typing is found. 34 | 35 | ## `listResource` 36 | Much like document resources, list resources can be used to fetch an array of 37 | documents. This type of resource will have additional methods for pagination and 38 | temporary storage of new entries. Support for linked fields is a strong focus 39 | point. List resources can support any arbitrary endpoint as long that endpoint 40 | satisfied parameters provided by `listResource`. 41 | 42 | ## Cache 43 | Having cache is a strong concern of this package. However it is not the primary 44 | objective. While cache brings some advantages, the side effects are not trivial. 45 | But expect this at some point in the near future. 46 | -------------------------------------------------------------------------------- /resource/useResource.ts: -------------------------------------------------------------------------------- 1 | import { useCallback, useEffect, useState } from 'react'; 2 | import { useApi } from '../api'; 3 | import type { FetchOptions, StrawError } from '../types'; 4 | 5 | interface UseResourceOptions extends FetchOptions { 6 | placeholder?: U; 7 | fetchOnMount?: boolean; 8 | transform?: (data: T) => U; 9 | } 10 | 11 | export interface Resource { 12 | data: T | undefined; 13 | loading: boolean; 14 | error: StrawError | null; 15 | fetched: boolean; 16 | refresh: (options?: FetchOptions) => Promise; 17 | setData: React.Dispatch>; 18 | } 19 | 20 | export function useResource( 21 | url: string, 22 | { 23 | method = 'get', 24 | body, 25 | params, 26 | placeholder, 27 | cache, 28 | cacheTime, 29 | fetchOnMount = true, 30 | transform = (data) => data as unknown as U, 31 | onSuccess, 32 | onError, 33 | onMessages, 34 | }: UseResourceOptions = {}, 35 | ): Resource { 36 | const apiRequest = useApi(); 37 | const [data, setData] = useState(placeholder); 38 | const [loading, setLoading] = useState(false); 39 | const [error, setError] = useState(null); 40 | const [fetched, setFetched] = useState(false); 41 | 42 | // Ensure URL is valid. 43 | const validUrl = 44 | url.startsWith('http') || url.startsWith('/') ? url : `/api/method/${url}`; 45 | 46 | const fetchData = useCallback( 47 | async (options: FetchOptions = {}) => { 48 | setLoading(true); 49 | setError(null); 50 | 51 | try { 52 | const response = await apiRequest({ 53 | url: validUrl, 54 | method, 55 | params: options.params || params, 56 | body: options.body || body, 57 | cache, 58 | cacheTime, 59 | onError, 60 | onMessages, 61 | }); 62 | const transformed = transform(response); 63 | setData(transformed); 64 | setFetched(true); 65 | onSuccess?.(transformed); 66 | return transformed; 67 | } catch (err: any) { 68 | setData(undefined); 69 | setError(err); 70 | onError?.(err); 71 | } finally { 72 | setLoading(false); 73 | } 74 | }, 75 | [apiRequest, url, method, body, params, cache], 76 | ); 77 | 78 | // Fetch data on mount. 79 | useEffect(() => { 80 | if (fetchOnMount) fetchData(); 81 | }, [ 82 | JSON.stringify({ 83 | url, 84 | params, 85 | body, 86 | }), 87 | ]); 88 | 89 | return { 90 | data, 91 | loading, 92 | error, 93 | fetched, 94 | refresh: fetchData, 95 | setData, 96 | }; 97 | } 98 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | .pnpm-debug.log* 9 | 10 | # Diagnostic reports (https://nodejs.org/api/report.html) 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 12 | 13 | # Runtime data 14 | pids 15 | *.pid 16 | *.seed 17 | *.pid.lock 18 | 19 | # Directory for instrumented libs generated by jscoverage/JSCover 20 | lib-cov 21 | 22 | # Coverage directory used by tools like istanbul 23 | coverage 24 | *.lcov 25 | 26 | # nyc test coverage 27 | .nyc_output 28 | 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 30 | .grunt 31 | 32 | # Bower dependency directory (https://bower.io/) 33 | bower_components 34 | 35 | # node-waf configuration 36 | .lock-wscript 37 | 38 | # Compiled binary addons (https://nodejs.org/api/addons.html) 39 | build/Release 40 | 41 | # Dependency directories 42 | node_modules/ 43 | jspm_packages/ 44 | 45 | # Snowpack dependency directory (https://snowpack.dev/) 46 | web_modules/ 47 | 48 | # TypeScript cache 49 | *.tsbuildinfo 50 | 51 | # Optional npm cache directory 52 | .npm 53 | 54 | # Optional eslint cache 55 | .eslintcache 56 | 57 | # Optional stylelint cache 58 | .stylelintcache 59 | 60 | # Microbundle cache 61 | .rpt2_cache/ 62 | .rts2_cache_cjs/ 63 | .rts2_cache_es/ 64 | .rts2_cache_umd/ 65 | 66 | # Optional REPL history 67 | .node_repl_history 68 | 69 | # Output of 'npm pack' 70 | *.tgz 71 | 72 | # Yarn Integrity file 73 | .yarn-integrity 74 | 75 | # dotenv environment variable files 76 | .env 77 | .env.development.local 78 | .env.test.local 79 | .env.production.local 80 | .env.local 81 | 82 | # parcel-bundler cache (https://parceljs.org/) 83 | .cache 84 | .parcel-cache 85 | 86 | # Next.js build output 87 | .next 88 | out 89 | 90 | # Nuxt.js build / generate output 91 | .nuxt 92 | dist 93 | 94 | # Gatsby files 95 | .cache/ 96 | # Comment in the public line in if your project uses Gatsby and not Next.js 97 | # https://nextjs.org/blog/next-9-1#public-directory-support 98 | # public 99 | 100 | # vuepress build output 101 | .vuepress/dist 102 | 103 | # vuepress v2.x temp and cache directory 104 | .temp 105 | .cache 106 | 107 | # Docusaurus cache and generated files 108 | .docusaurus 109 | 110 | # Serverless directories 111 | .serverless/ 112 | 113 | # FuseBox cache 114 | .fusebox/ 115 | 116 | # DynamoDB Local files 117 | .dynamodb/ 118 | 119 | # TernJS port file 120 | .tern-port 121 | 122 | # Stores VSCode versions used for testing VSCode extensions 123 | .vscode-test 124 | 125 | # yarn v2 126 | .yarn/cache 127 | .yarn/unplugged 128 | .yarn/build-state.yml 129 | .yarn/install-state.gz 130 | .pnp.* 131 | -------------------------------------------------------------------------------- /document/index.ts: -------------------------------------------------------------------------------- 1 | import { useMemo } from 'react'; 2 | import { useResource } from '../resource'; 3 | import type { BaseDocument, FetchOptions } from '../types'; 4 | import { useAction } from './useAction'; 5 | import { useDelete } from './useDelete'; 6 | import { useMethod } from './useMethod'; 7 | import { useStatus } from './useStatus'; 8 | import { useTimeAgo } from './useTimeAgo'; 9 | 10 | interface UseDocumentOptions extends FetchOptions { 11 | fetchOnMount?: boolean; 12 | } 13 | 14 | interface Document 15 | extends ReturnType> { 16 | canSave: boolean; 17 | canSubmit: boolean; 18 | canCancel: boolean; 19 | useStatus: () => ReturnType>; 20 | useTimeAgo: () => ReturnType>; 21 | useSave: (options?: FetchOptions) => ReturnType>; 22 | useSubmit: (options?: FetchOptions) => ReturnType>; 23 | useCancel: (options?: FetchOptions) => ReturnType>; 24 | useMethod: (method: string) => ReturnType>; 25 | useDelete: (options?: FetchOptions) => ReturnType; 26 | } 27 | 28 | /** 29 | * Hook for managing a document resource. 30 | * @param doctype - Document type. 31 | * @param docname - Document name. 32 | * @returns `DocumentResource` 33 | */ 34 | export function useDocument( 35 | doctype: string, 36 | docname: string, 37 | { 38 | cache, 39 | cacheTime, 40 | fetchOnMount = true, 41 | onSuccess, 42 | onError, 43 | onMessages, 44 | }: UseDocumentOptions = {}, 45 | ): Document { 46 | const url = useMemo(() => { 47 | return ( 48 | '/api/resource/' + 49 | encodeURIComponent(doctype) + 50 | '/' + 51 | encodeURIComponent(docname) 52 | ); 53 | }, [doctype, docname]); 54 | 55 | const resource = useResource<{ data: T }, T>(url, { 56 | cache, 57 | cacheTime, 58 | fetchOnMount, 59 | transform: (data) => data.data, 60 | onSuccess, 61 | onError, 62 | onMessages, 63 | }); 64 | 65 | const data = resource.data; 66 | const setData = resource.setData; 67 | const docstatus = data?.docstatus; 68 | 69 | const canSave = useMemo(() => docstatus === 0, [docstatus]); 70 | const canSubmit = useMemo(() => docstatus === 0, [docstatus]); 71 | const canCancel = useMemo(() => docstatus === 1, [docstatus]); 72 | 73 | return { 74 | ...resource, 75 | canSave, 76 | canSubmit, 77 | canCancel, 78 | useStatus: () => useStatus(data), 79 | useTimeAgo: () => useTimeAgo(data), 80 | useSave: (options) => useAction('Save', doctype, data, setData, options), 81 | useSubmit: (options) => 82 | useAction('Submit', doctype, data, setData, options), 83 | useCancel: (options) => 84 | useAction('Cancel', doctype, data, setData, options), 85 | useMethod: (method: string) => { 86 | return useMethod(method, doctype, docname, setData); 87 | }, 88 | useDelete: (options) => useDelete(doctype, docname, options), 89 | }; 90 | } 91 | -------------------------------------------------------------------------------- /assets/bytsolv-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 17 | 19 | 28 | 36 | 37 | 45 | 51 | 52 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | /* Visit https://aka.ms/tsconfig to read more about this file */ 4 | 5 | /* Projects */ 6 | // "incremental": true, /* Save .tsbuildinfo files to allow for incremental compilation of projects. */ 7 | // "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */ 8 | // "tsBuildInfoFile": "./.tsbuildinfo", /* Specify the path to .tsbuildinfo incremental compilation file. */ 9 | // "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects. */ 10 | // "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */ 11 | // "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */ 12 | 13 | /* Language and Environment */ 14 | "target": "es2019", /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */ 15 | // "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */ 16 | "jsx": "react-jsx", /* Specify what JSX code is generated. */ 17 | // "experimentalDecorators": true, /* Enable experimental support for legacy experimental decorators. */ 18 | // "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */ 19 | // "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */ 20 | // "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */ 21 | // "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */ 22 | // "reactNamespace": "", /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */ 23 | // "noLib": true, /* Disable including any library files, including the default lib.d.ts. */ 24 | // "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */ 25 | // "moduleDetection": "auto", /* Control what method is used to detect module-format JS files. */ 26 | 27 | /* Modules */ 28 | "module": "commonjs", /* Specify what module code is generated. */ 29 | // "rootDir": "./", /* Specify the root folder within your source files. */ 30 | // "moduleResolution": "node10", /* Specify how TypeScript looks up a file from a given module specifier. */ 31 | // "baseUrl": "./", /* Specify the base directory to resolve non-relative module names. */ 32 | // "paths": {}, /* Specify a set of entries that re-map imports to additional lookup locations. */ 33 | // "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */ 34 | // "typeRoots": [], /* Specify multiple folders that act like './node_modules/@types'. */ 35 | // "types": [], /* Specify type package names to be included without being referenced in a source file. */ 36 | // "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */ 37 | // "moduleSuffixes": [], /* List of file name suffixes to search when resolving a module. */ 38 | // "allowImportingTsExtensions": true, /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */ 39 | // "rewriteRelativeImportExtensions": true, /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */ 40 | // "resolvePackageJsonExports": true, /* Use the package.json 'exports' field when resolving package imports. */ 41 | // "resolvePackageJsonImports": true, /* Use the package.json 'imports' field when resolving imports. */ 42 | // "customConditions": [], /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */ 43 | // "noUncheckedSideEffectImports": true, /* Check side effect imports. */ 44 | // "resolveJsonModule": true, /* Enable importing .json files. */ 45 | // "allowArbitraryExtensions": true, /* Enable importing files with any extension, provided a declaration file is present. */ 46 | // "noResolve": true, /* Disallow 'import's, 'require's or ''s from expanding the number of files TypeScript should add to a project. */ 47 | 48 | /* JavaScript Support */ 49 | // "allowJs": true, /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */ 50 | // "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */ 51 | // "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */ 52 | 53 | /* Emit */ 54 | // "declaration": true, /* Generate .d.ts files from TypeScript and JavaScript files in your project. */ 55 | // "declarationMap": true, /* Create sourcemaps for d.ts files. */ 56 | // "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */ 57 | // "sourceMap": true, /* Create source map files for emitted JavaScript files. */ 58 | // "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */ 59 | "noEmit": true, /* Disable emitting files from a compilation. */ 60 | // "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */ 61 | // "outDir": "./", /* Specify an output folder for all emitted files. */ 62 | // "removeComments": true, /* Disable emitting comments. */ 63 | // "importHelpers": true, /* Allow importing helper functions from tslib once per project, instead of including them per-file. */ 64 | // "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */ 65 | // "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */ 66 | // "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */ 67 | // "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */ 68 | // "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */ 69 | // "newLine": "crlf", /* Set the newline character for emitting files. */ 70 | // "stripInternal": true, /* Disable emitting declarations that have '@internal' in their JSDoc comments. */ 71 | // "noEmitHelpers": true, /* Disable generating custom helper functions like '__extends' in compiled output. */ 72 | // "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */ 73 | // "preserveConstEnums": true, /* Disable erasing 'const enum' declarations in generated code. */ 74 | // "declarationDir": "./", /* Specify the output directory for generated declaration files. */ 75 | 76 | /* Interop Constraints */ 77 | // "isolatedModules": true, /* Ensure that each file can be safely transpiled without relying on other imports. */ 78 | // "verbatimModuleSyntax": true, /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */ 79 | // "isolatedDeclarations": true, /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */ 80 | // "allowSyntheticDefaultImports": true, /* Allow 'import x from y' when a module doesn't have a default export. */ 81 | "esModuleInterop": true, /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */ 82 | // "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */ 83 | "forceConsistentCasingInFileNames": true, /* Ensure that casing is correct in imports. */ 84 | 85 | /* Type Checking */ 86 | "strict": true, /* Enable all strict type-checking options. */ 87 | // "noImplicitAny": true, /* Enable error reporting for expressions and declarations with an implied 'any' type. */ 88 | // "strictNullChecks": true, /* When type checking, take into account 'null' and 'undefined'. */ 89 | // "strictFunctionTypes": true, /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */ 90 | // "strictBindCallApply": true, /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */ 91 | // "strictPropertyInitialization": true, /* Check for class properties that are declared but not set in the constructor. */ 92 | // "strictBuiltinIteratorReturn": true, /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */ 93 | // "noImplicitThis": true, /* Enable error reporting when 'this' is given the type 'any'. */ 94 | // "useUnknownInCatchVariables": true, /* Default catch clause variables as 'unknown' instead of 'any'. */ 95 | // "alwaysStrict": true, /* Ensure 'use strict' is always emitted. */ 96 | // "noUnusedLocals": true, /* Enable error reporting when local variables aren't read. */ 97 | // "noUnusedParameters": true, /* Raise an error when a function parameter isn't read. */ 98 | // "exactOptionalPropertyTypes": true, /* Interpret optional property types as written, rather than adding 'undefined'. */ 99 | // "noImplicitReturns": true, /* Enable error reporting for codepaths that do not explicitly return in a function. */ 100 | // "noFallthroughCasesInSwitch": true, /* Enable error reporting for fallthrough cases in switch statements. */ 101 | // "noUncheckedIndexedAccess": true, /* Add 'undefined' to a type when accessed using an index. */ 102 | // "noImplicitOverride": true, /* Ensure overriding members in derived classes are marked with an override modifier. */ 103 | // "noPropertyAccessFromIndexSignature": true, /* Enforces using indexed accessors for keys declared using an indexed type. */ 104 | // "allowUnusedLabels": true, /* Disable error reporting for unused labels. */ 105 | // "allowUnreachableCode": true, /* Disable error reporting for unreachable code. */ 106 | 107 | /* Completeness */ 108 | // "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */ 109 | "skipLibCheck": true /* Skip type checking all .d.ts files. */ 110 | } 111 | } 112 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | --------------------------------------------------------------------------------